@fedify/fedify 0.9.0-dev.172 → 0.9.0-dev.173

package/CHANGES.md

@@ -12,6 +12,17 @@ To be released.
 
  -  Added `Emoji` class to Activity Vocabulary API.  [[#48]]
 
+ -  Added an actor handle normalization function.
+
+     -  Added `normalizeActorHandle()` function.
+     -  Added `NormalizeActorHandleOptions` interface.
+     -  The `getActorHandle()` function now guarantees that the returned
+        actor handle is normalized.
+     -  Added the second optional parameter to `getActorHandle()` function.
+     -  The return type of `getActorHandle()` function became
+        ``Promise<`@${string}@${string}` | `${string}@${string}`>``
+        (was ``Promise<`@${string}@${string}`>``).
+
  -  Added more log messages using the [LogTape] library.  Currently the below
     logger categories are used:
 

package/esm/vocab/actor.js

@@ -1,3 +1,4 @@
+import { toASCII, toUnicode } from "node:punycode";
 import { lookupWebFinger } from "../webfinger/lookup.js";
 import { Application, Group, Organization, Person, Service } from "./vocab.js";
 /**
@@ -66,13 +67,15 @@ export function getActorClassByTypeName(typeName) {
  * ```
  *
  * @param actor The actor or actor URI to get the handle from.
+ * @param options The options for normalizing the actor handle.
  * @returns The actor handle.  It starts with `@` and is followed by the
- *          username and domain, separated by `@`.
+ *          username and domain, separated by `@` by default (it can be
+ *          customized with the options).
  * @throws {TypeError} If the actor does not have enough information to get the
  *                     handle.
  * @since 0.4.0
  */
-export async function getActorHandle(actor) {
+export async function getActorHandle(actor, options = {}) {
     const actorId = actor instanceof URL ? actor : actor.id;
     if (actorId != null) {
         const result = await lookupWebFinger(actorId);
@@ -82,14 +85,37 @@ export async function getActorHandle(actor) {
                 aliases.unshift(result.subject);
             for (const alias of aliases) {
                 const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
-                if (match != null)
-                    return `@${match[1]}@${match[2]}`;
+                if (match != null) {
+                    return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
+                }
             }
         }
     }
     if (!(actor instanceof URL) && actor.preferredUsername != null &&
         actor.id != null) {
-        return `@${actor.preferredUsername}@${actor.id.host}`;
+        return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
     }
     throw new TypeError("Actor does not have enough information to get the handle.");
 }
+/**
+ * Normalizes the given actor handle.
+ * @param handle The full handle of the actor to normalize.
+ * @param options The options for normalizing the actor handle.
+ * @returns The normalized actor handle.
+ * @throws {TypeError} If the actor handle is invalid.
+ */
+export function normalizeActorHandle(handle, options = {}) {
+    handle = handle.replace(/^@/, "");
+    const atPos = handle.indexOf("@");
+    if (atPos < 1)
+        throw new TypeError("Invalid actor handle.");
+    let domain = handle.substring(atPos + 1);
+    if (domain.length < 1 || domain.includes("@")) {
+        throw new TypeError("Invalid actor handle.");
+    }
+    domain = domain.toLowerCase();
+    domain = options.punycode ? toASCII(domain) : toUnicode(domain);
+    domain = domain.toLowerCase();
+    const user = handle.substring(0, atPos);
+    return options.trimLeadingAt ? `${user}@${domain}` : `@${user}@${domain}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/fedify",
-  "version": "0.9.0-dev.172+738f84bf",
+  "version": "0.9.0-dev.173+42b64481",
   "description": "An ActivityPub server framework",
   "keywords": [
     "ActivityPub",

package/types/vocab/actor.d.ts

@@ -43,13 +43,39 @@ export declare function getActorClassByTypeName(typeName: ActorTypeName): typeof
  * ```
  *
  * @param actor The actor or actor URI to get the handle from.
+ * @param options The options for normalizing the actor handle.
  * @returns The actor handle.  It starts with `@` and is followed by the
- *          username and domain, separated by `@`.
+ *          username and domain, separated by `@` by default (it can be
+ *          customized with the options).
  * @throws {TypeError} If the actor does not have enough information to get the
  *                     handle.
  * @since 0.4.0
  */
-export declare function getActorHandle(actor: Actor | URL): Promise<`@${string}@${string}`>;
+export declare function getActorHandle(actor: Actor | URL, options?: NormalizeActorHandleOptions): Promise<`@${string}@${string}` | `${string}@${string}`>;
+/**
+ * Options for {@link normalizeActorHandle}.
+ * @since 0.9.0
+ */
+export interface NormalizeActorHandleOptions {
+    /**
+     * Whether to trim the leading `@` from the actor handle.  Turned off by
+     * default.
+     */
+    trimLeadingAt?: boolean;
+    /**
+     * Whether to convert the domain part of the actor handle to punycode, if it
+     * is an internationalized domain name.  Turned off by default.
+     */
+    punycode?: boolean;
+}
+/**
+ * Normalizes the given actor handle.
+ * @param handle The full handle of the actor to normalize.
+ * @param options The options for normalizing the actor handle.
+ * @returns The normalized actor handle.
+ * @throws {TypeError} If the actor handle is invalid.
+ */
+export declare function normalizeActorHandle(handle: string, options?: NormalizeActorHandleOptions): `@${string}@${string}` | `${string}@${string}`;
 /**
  * The object that can be a recipient of an activity.
  *

package/types/vocab/actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../src/vocab/actor.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,WAAW,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,KAAK,CAQxD;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,OAAO,GACP,cAAc,GACd,QAAQ,GACR,SAAS,CAAC;AAEd;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,GACX,aAAa,CAOf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,GAErB,OAAO,WAAW,GAClB,OAAO,KAAK,GACZ,OAAO,YAAY,GACnB,OAAO,MAAM,GACb,OAAO,OAAO,CAcjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,KAAK,GAAG,GAAG,GACjB,OAAO,CAAC,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC,CAsBjC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,IAAI,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB;;WAEG;QACH,WAAW,EAAE,GAAG,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI,CAAC;CACV"}
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../src/vocab/actor.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,WAAW,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,KAAK,CAQxD;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,OAAO,GACP,cAAc,GACd,QAAQ,GACR,SAAS,CAAC;AAEd;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,GACX,aAAa,CAOf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,GAErB,OAAO,WAAW,GAClB,OAAO,KAAK,GACZ,OAAO,YAAY,GACnB,OAAO,MAAM,GACb,OAAO,OAAO,CAcjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,KAAK,GAAG,GAAG,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,IAAI,MAAM,IAAI,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC,CA2BzD;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GACxC,IAAI,MAAM,IAAI,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAahD;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,IAAI,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB;;WAEG;QACH,WAAW,EAAE,GAAG,GAAG,IAAI,CAAC;KACzB,GAAG,IAAI,CAAC;CACV"}