Compatible FEP-ef61 identifiers for portable objects

[dahlia]

Background

FEP-ef61 defines gateway-compatible HTTP(S) identifiers for portable objects. These identifiers allow objects with portable ap:/ap+ef61: IDs to interoperate with ActivityPub implementations that still expect object IDs to be ordinary HTTP(S) URLs.

For example, this portable identifier:

ap+ef61://did:key:z6MkAlice/objects/1

can be represented as this compatible identifier through a gateway:

https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1

Implementations that understand FEP-ef61 should be able to convert the compatible identifier back into the canonical portable identifier:

ap+ef61://did:key:z6MkAlice/objects/1

The reverse conversion is also needed when Fedify needs to publish objects to implementations that do not understand portable URI schemes.

This issue is only about converting identifiers. Actual gateway dereferencing should be handled separately.

Proposed work

Add helper functions for converting between canonical portable identifiers and FEP-ef61 compatible HTTP(S) identifiers.

The helpers should:

• convert a fixed well-known compatible identifier into a canonical ap+ef61: portable URI;
• convert a canonical portable URI into a fixed well-known compatible identifier using a given gateway base URL;
• accept ap: and ap+ef61: portable URI inputs, normalizing to ap+ef61: where canonical output is needed;
• preserve the portable URI path and fragment where applicable;
• avoid adding the gateways query parameter to compatible object IDs;
• reject malformed compatible identifiers;
• reject gateway base URLs that are not HTTP(S) origins;
• keep arbitrary gateway paths out of scope for the initial implementation.

The intended API can be decided during implementation, but it could look roughly like:

fromCompatibleEf61Id(input: string | URL): URL | null;
toCompatibleEf61Id(portableId: string | URL, gateway: string | URL): URL;

fromCompatibleEf61Id() should return null when the input is not a compatible FEP-ef61 identifier. If the input appears to be a compatible identifier but is malformed, it should throw a TypeError.

toCompatibleEf61Id() should throw a TypeError when the portable ID or gateway URL is invalid.

Scope

This issue is only about fixed-path compatible identifier conversion.

It does not include:

• gateway dereferencing;
• gateway endpoint implementation;
• arbitrary gateway path support;
• actor gateways selection policy beyond accepting an explicit gateway input;
• network fetch behavior;
• Object Integrity Proof verification;
• FEP-fe34 origin checks.

Gateway dereferencing should be handled in a separate follow-up issue under #288.

Tests

Add regression tests for compatible identifier conversion.

The tests should cover:

• converting https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1 to ap+ef61://did:key:z6MkAlice/objects/1;
• converting an ap+ef61: portable ID and https://server.example gateway into the expected compatible ID;
• accepting ap: input and producing ap+ef61: canonical form where appropriate;
• preserving path components;
• preserving fragment components where applicable;
• rejecting compatible object IDs with malformed DID/path parts;
• returning null for unrelated HTTP(S) URLs;
• rejecting non-HTTP(S) gateway URLs;
• ensuring compatible object IDs do not include gateways query hints.

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