洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

Yes, we probably should have had this sooner… but hey, proper domain handling is coming to 1.5.0!

https://hollo.social/@fedify/01953693-1afd-7430-988a-23d649099e1c

Fedify: an ActivityPub server framework's avatar
Fedify: an ActivityPub server framework

@fedify@hollo.social

We're excited to announce two major features coming in 1.5.0, focused on giving you more control over domain names in your federated apps:

Separate WebFinger Host from Server Origin

Want different domains for your WebFinger handles and server URIs? Fedify 1.5.0 will let you use domains like @alice@example.com as fediverse handles while serving content from https://ap.example.com. This gives you more flexibility in how you structure your federated services.

Canonical Origin Support

Need to ensure consistent URLs across your infrastructure? The new canonical origin support lets you explicitly set your server's authoritative domain. This is particularly useful when running behind reverse proxies or load balancers—no more unexpected URLs generated from internal hostnames.

These features represent our ongoing commitment to making Fedify more flexible and production-ready.

Can't wait to try these features? You can experiment with them today using our unstable release v1.5.0-dev.680+562e3dc0 (JSR & npm). Keep in mind that this is an unstable release intended for testing—use it in production at your own risk.

Otherwise, stay tuned for the stable Fedify 1.5.0 release!

Separating WebFinger host from the server origin This API is available since Fedify 1.5.0. Sometimes you may want to use different domain names for WebFinger handles (i.e., fediverse handles) and the server origin. For example, you may want to use https://ap.example.com/actors/alice as an actor URI but want to use @alice@example.com as its fediverse handle. In such cases, you can set the handleHost different from the webOrigin in the origin option. The handleHost is used to construct the WebFinger handles, and the webOrigin is used to construct the URLs in the Context object: const federation = createFederation({ origin: { handleHost: "example.com", webOrigin: "https://ap.example.com", }, }); NOTE Even if you set the handleHost different from the webOrigin, the other fediverse handle with the same domain name as the webOrigin will still be recognized. In the above example, two fediverse handles are recognized as the same: • @alice@example.com • @alice@ap.example.com
ALT text detailsSeparating WebFinger host from the server origin This API is available since Fedify 1.5.0. Sometimes you may want to use different domain names for WebFinger handles (i.e., fediverse handles) and the server origin. For example, you may want to use https://ap.example.com/actors/alice as an actor URI but want to use @alice@example.com as its fediverse handle. In such cases, you can set the handleHost different from the webOrigin in the origin option. The handleHost is used to construct the WebFinger handles, and the webOrigin is used to construct the URLs in the Context object: const federation = createFederation({ origin: { handleHost: "example.com", webOrigin: "https://ap.example.com", }, }); NOTE Even if you set the handleHost different from the webOrigin, the other fediverse handle with the same domain name as the webOrigin will still be recognized. In the above example, two fediverse handles are recognized as the same: • @alice@example.com • @alice@ap.example.com
Explicitly setting the canonical origin This API is available since Fedify 1.5.0. Or you can explicitly set the canonical origin of the server by passing the origin option to the createFederation() function. The origin option is either a string or a FederationOrigin object, which consists of two fields: handleHost and webOrigin. For example, if you want to set the canonical origin to https://example.com, you can pass the string: const federation = createFederation({ origin: "https://example.com", }); NOTE The origin option has to include the leading https:// or http:// scheme. Such a configuration leads the constructed URLs using Context to use the canonical origin instead of the origin from the incoming HTTP requests, which avoids constructing unexpected URLs when a request bypasses a reverse proxy or a load balancer. CAUTION For example, suppose that your federated server (upstream) is accessible at the http://1.2.3.4:8000 and your load balancer (downstream) is accessible at the https://example.com and forwards the requests to the upstream server. In this case, you should set the canonical origin to https://example.com to construct the correct URLs. Otherwise, when some malicious actor directly sends a request to the upstream server, the constructed URLs will start with http://1.2.3.4:8000 instead of https://example.com, which can lead to security issues.
ALT text detailsExplicitly setting the canonical origin This API is available since Fedify 1.5.0. Or you can explicitly set the canonical origin of the server by passing the origin option to the createFederation() function. The origin option is either a string or a FederationOrigin object, which consists of two fields: handleHost and webOrigin. For example, if you want to set the canonical origin to https://example.com, you can pass the string: const federation = createFederation({ origin: "https://example.com", }); NOTE The origin option has to include the leading https:// or http:// scheme. Such a configuration leads the constructed URLs using Context to use the canonical origin instead of the origin from the incoming HTTP requests, which avoids constructing unexpected URLs when a request bypasses a reverse proxy or a load balancer. CAUTION For example, suppose that your federated server (upstream) is accessible at the http://1.2.3.4:8000 and your load balancer (downstream) is accessible at the https://example.com and forwards the requests to the upstream server. In this case, you should set the canonical origin to https://example.com to construct the correct URLs. Otherwise, when some malicious actor directly sends a request to the upstream server, the constructed URLs will start with http://1.2.3.4:8000 instead of https://example.com, which can lead to security issues.