Harden fixed-path actor aliases and address review feedback

Harden `mapActorAlias()` by adding a duplicate registration guard and
using a constant for the alias prefix.  Updated JSDoc to include the
`RouterError` contract.

Improved test coverage with a duplicate alias registration test and
added a null-guard for WebFinger aliases in the middleware test.
Also added a title to `pr-description.md`.

#753 (comment)
#753 (comment)
#753 (comment)
#753 (comment)
#753 (comment)
#753 (comment)

Assisted-by: Gemini CLI:gemini-3-flash-preview
Assisted-by: Codex:gpt-5.5

Author: dahlia

packages/fedify/src/federation/builder.test.ts

@@ -35,6 +35,15 @@ test("FederationBuilder", async (t) => {
         RouterError,
         "Path for actor alias must have no variables.",
       );
+      assertThrows(
+        () =>
+          createFederationBuilder<string>()
+            .setActorDispatcher("/users/{identifier}", actorDispatcher)
+            .mapActorAlias("/actor", "instance")
+            .mapActorAlias("/bot", "instance"),
+        RouterError,
+        'Actor alias for "instance" already set.',
+      );
       builder.setActorDispatcher("/users/{identifier}", actorDispatcher)
         .mapActorAlias("/actor", "instance");
 

packages/fedify/src/federation/builder.ts

@@ -63,6 +63,8 @@ import type {
 } from "./handler.ts";
 import { Router, RouterError } from "./router.ts";
 
+const ACTOR_ALIAS_PREFIX = "actorAlias:";
+
 function validateSingleIdentifierVariablePath(
   path: string,
   errorMessage: string,
@@ -523,13 +525,18 @@ export class FederationBuilderImpl<TContextData>
         return setters;
       },
       mapActorAlias: (path: string, identifier: string) => {
+        if (this.router.has(`${ACTOR_ALIAS_PREFIX}${identifier}`)) {
+          throw new RouterError(
+            `Actor alias for "${identifier}" already set.`,
+          );
+        }
         const variables = new Router().add(path, "temp");
         if (variables.size > 0) {
           throw new RouterError(
             "Path for actor alias must have no variables.",
           );
         }
-        this.router.add(path, `actorAlias:${identifier}`);
+        this.router.add(path, `${ACTOR_ALIAS_PREFIX}${identifier}`);
         return setters;
       },
       authorize(predicate: AuthorizePredicate<TContextData>) {

packages/fedify/src/federation/federation.ts

@@ -1115,6 +1115,8 @@ export interface ActorCallbackSetters<TContextData> {
    * @param path The fixed path to map to the identifier.
    * @param identifier The sentinel identifier to map the path to.
    * @returns The setters object so that settings can be chained.
+   * @throws {RouterError} If the provided path or identifier is invalid or fails
+   *                       runtime validation.
    * @since 2.3.0
    */
   mapActorAlias(

packages/fedify/src/federation/middleware.test.ts

@@ -1219,6 +1219,7 @@ test("Federation.fetch()", async (t) => {
     );
     assertExists(selfLink);
     assertEquals(selfLink.href, "https://example.com/bot");
+    assertExists(body.aliases);
     assert((body.aliases as string[]).includes("https://example.com/bot"));
   });
 

packages/fedify/src/federation/middleware.ts

@@ -112,6 +112,8 @@ import type {
 } from "./queue.ts";
 import { createExponentialBackoffPolicy, type RetryPolicy } from "./retry.ts";
 import { RouterError } from "./router.ts";
+
+const ACTOR_ALIAS_PREFIX = "actorAlias:";
 import {
   extractInboxes,
   sendActivity,
@@ -1437,8 +1439,8 @@ export class FederationImpl<TContextData>
     switch (routeName) {
       case "actor":
       case "actorAlias": {
-        const identifier = route.name.startsWith("actorAlias:")
-          ? route.name.substring("actorAlias:".length)
+        const identifier = route.name.startsWith(ACTOR_ALIAS_PREFIX)
+          ? route.name.substring(ACTOR_ALIAS_PREFIX.length)
           : route.values.identifier;
         context = this.#createContext(request, contextData, {
           invokedFromActorDispatcher: { identifier },
@@ -1793,7 +1795,7 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
 
   getActorUri(identifier: string): URL {
     let path = this.federation.router.build(
-      `actorAlias:${identifier}`,
+      `${ACTOR_ALIAS_PREFIX}${identifier}`,
       {},
     );
     if (path == null) {
@@ -1947,10 +1949,10 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
         identifier: undefined,
       };
     }
-    const identifier = route.name.startsWith("actorAlias:")
-      ? route.name.substring("actorAlias:".length)
+    const identifier = route.name.startsWith(ACTOR_ALIAS_PREFIX)
+      ? route.name.substring(ACTOR_ALIAS_PREFIX.length)
       : route.values.identifier;
-    if (route.name === "actor" || route.name.startsWith("actorAlias:")) {
+    if (route.name === "actor" || route.name.startsWith(ACTOR_ALIAS_PREFIX)) {
       return {
         type: "actor",
         identifier,

pr-description.md

@@ -1,3 +1,6 @@
+Support fixed-path actor dispatchers (`mapActorAlias()`)
+========================================================
+
 This PR adds `mapActorAlias()` to `ActorCallbackSetters`. An actor dispatcher
 can now map a fixed path, such as `/actor` or `/bot`, to an internal sentinel
 identifier.