@fedify/fedify 1.3.0-dev.484 → 1.3.0-dev.485

package/CHANGES.md

@@ -8,9 +8,29 @@ Version 1.3.0
 
 To be released.
 
- -  Fedify now makes HTTP requests with the proper `User-Agent` header.
+ -  Fedify now makes HTTP requests with the proper `User-Agent` header. [[#162]]
 
      -  Added `getUserAgent()` function.
+     -  Added `GetUserAgentOptions` interface.
+     -  Added `getDocumentLoader()` function.
+     -  Added `GetDocumentLoaderOptions` interface.
+     -  The type of `getAuthenticatedDocumentLoader()` function's second
+        parameter became `GetAuthenticatedDocumentLoaderOptions | undefined`
+        (was `boolean | undefined`).
+     -  Added `GetAuthenticatedDocumentLoaderOptions` interface.
+     -  Deprecated `fetchDocumentLoader()` function.
+     -  Added `LookupObjectOptions.userAgent` option.
+     -  Added the type of `getActorHandle()` function's second parameter became
+        `GetActorHandleOptions | undefined` (was `NormalizeActorHandleOptions |
+        undefined`).
+     -  Added `GetActorHandleOptions` interface.
+     -  Added the optional second parameter to `lookupWebFinger()` function.
+     -  Added `LookupWebFingerOptions` interface.
+     -  Added `GetNodeInfoOptions.userAgent` option.
+     -  Added `-u`/--user-agent` option to `fedify lookup` subcommand.
+     -  Added `-u`/--user-agent` option to `fedify node` subcommand.
+
+[#162]: https://github.com/dahlia/fedify/issues/162
 
 
 Version 1.2.2

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "@fedify/fedify",
-    "version": "1.3.0-dev.484+e6a416f0",
+    "version": "1.3.0-dev.485+cfe509f3",
     "license": "MIT",
     "exports": {
         ".": "./mod.ts",

package/esm/federation/middleware.js

@@ -1,7 +1,7 @@
 import * as dntShim from "../_dnt.shims.js";
 import { getLogger, withContext } from "@logtape/logtape";
 import { handleNodeInfo, handleNodeInfoJrd } from "../nodeinfo/handler.js";
-import { fetchDocumentLoader, getAuthenticatedDocumentLoader, kvCache, } from "../runtime/docloader.js";
+import { getAuthenticatedDocumentLoader, getDocumentLoader, kvCache, } from "../runtime/docloader.js";
 import { verifyRequest } from "../sig/http.js";
 import { exportJwk, importJwk, validateCryptoKey } from "../sig/key.js";
 import { hasSignature, signJsonLd } from "../sig/ld.js";
@@ -50,6 +50,7 @@ export class FederationImpl {
     documentLoader;
     contextLoader;
     authenticatedDocumentLoaderFactory;
+    userAgent;
     onOutboxError;
     signatureTimeWindow;
     skipSignatureVerification;
@@ -75,31 +76,34 @@ export class FederationImpl {
         this.router.add("/.well-known/nodeinfo", "nodeInfoJrd");
         this.objectCallbacks = {};
         this.objectTypeIds = {};
-        if (options.allowPrivateAddress) {
+        if (options.allowPrivateAddress || options.userAgent != null) {
             if (options.documentLoader != null) {
-                throw new TypeError("Cannot set documentLoader with allowPrivateAddress turned on.");
+                throw new TypeError("Cannot set documentLoader with allowPrivateAddress or " +
+                    "userAgent options.");
             }
             else if (options.contextLoader != null) {
-                throw new TypeError("Cannot set contextLoader with allowPrivateAddress turned on.");
+                throw new TypeError("Cannot set contextLoader with allowPrivateAddress or " +
+                    "userAgent options.");
             }
             else if (options.authenticatedDocumentLoaderFactory != null) {
                 throw new TypeError("Cannot set authenticatedDocumentLoaderFactory with " +
-                    "allowPrivateAddress turned on.");
+                    "allowPrivateAddress or userAgent options.");
             }
         }
+        const { allowPrivateAddress, userAgent } = options;
         this.documentLoader = options.documentLoader ?? kvCache({
-            loader: options.allowPrivateAddress
-                ? (url) => fetchDocumentLoader(url, true)
-                : fetchDocumentLoader,
+            loader: getDocumentLoader({ allowPrivateAddress, userAgent }),
             kv: options.kv,
             prefix: this.kvPrefixes.remoteDocument,
         });
         this.contextLoader = options.contextLoader ?? this.documentLoader;
         this.authenticatedDocumentLoaderFactory =
             options.authenticatedDocumentLoaderFactory ??
-                (options.allowPrivateAddress
-                    ? (identity) => getAuthenticatedDocumentLoader(identity, true)
-                    : getAuthenticatedDocumentLoader);
+                ((identity) => getAuthenticatedDocumentLoader(identity, {
+                    allowPrivateAddress,
+                    userAgent,
+                }));
+        this.userAgent = userAgent;
         this.onOutboxError = options.onOutboxError;
         this.signatureTimeWindow = options.signatureTimeWindow ?? { hours: 1 };
         this.skipSignatureVerification = options.skipSignatureVerification ?? false;
@@ -1554,6 +1558,7 @@ export class ContextImpl {
         return lookupObject(identifier, {
             documentLoader: options.documentLoader ?? this.documentLoader,
             contextLoader: options.contextLoader ?? this.contextLoader,
+            userAgent: options.userAgent ?? this.federation.userAgent,
         });
     }
     traverseCollection(collection, options = {}) {

package/esm/nodeinfo/client.js

@@ -1,6 +1,6 @@
 import { getLogger } from "@logtape/logtape";
 import { parse } from "../deps/jsr.io/@std/semver/1.0.3/mod.js";
-import { getUserAgent } from "../runtime/docloader.js";
+import { getUserAgent, } from "../runtime/docloader.js";
 const logger = getLogger(["fedify", "nodeinfo", "client"]);
 export async function getNodeInfo(url, options = {}) {
     try {
@@ -10,7 +10,9 @@ export async function getNodeInfo(url, options = {}) {
             const wellKnownResponse = await fetch(wellKnownUrl, {
                 headers: {
                     Accept: "application/json",
-                    "User-Agent": getUserAgent(),
+                    "User-Agent": typeof options.userAgent === "string"
+                        ? options.userAgent
+                        : getUserAgent(options.userAgent),
                 },
             });
             if (!wellKnownResponse.ok) {
@@ -37,7 +39,9 @@ export async function getNodeInfo(url, options = {}) {
         const response = await fetch(nodeInfoUrl, {
             headers: {
                 Accept: "application/json",
-                "User-Agent": getUserAgent(),
+                "User-Agent": typeof options.userAgent === "string"
+                    ? options.userAgent
+                    : getUserAgent(options.userAgent),
             },
         });
         if (!response.ok) {

package/esm/runtime/docloader.js

@@ -28,11 +28,13 @@ export class FetchError extends Error {
         this.url = typeof url === "string" ? new URL(url) : url;
     }
 }
-function createRequest(url) {
+function createRequest(url, options = {}) {
     return new Request(url, {
         headers: {
             Accept: "application/activity+json, application/ld+json",
-            "User-Agent": getUserAgent(),
+            "User-Agent": typeof options.userAgent === "string"
+                ? options.userAgent
+                : getUserAgent(options.userAgent),
         },
         redirect: "manual",
     });
@@ -128,6 +130,65 @@ async function getRemoteDocument(url, response, fetch) {
         documentUrl,
     };
 }
+/**
+ * Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
+ *
+ * The created loader preloads the below frequently used contexts by default
+ * (unless `options.ignorePreloadedContexts` is set to `true`):
+ *
+ * - <https://www.w3.org/ns/activitystreams>
+ * - <https://w3id.org/security/v1>
+ * - <https://w3id.org/security/data-integrity/v1>
+ * - <https://www.w3.org/ns/did/v1>
+ * - <https://w3id.org/security/multikey/v1>
+ * - <https://purl.archive.org/socialweb/webfinger>
+ * - <http://schema.org/>
+ * @param options Options for the document loader.
+ * @returns The document loader.
+ * @since 1.3.0
+ */
+export function getDocumentLoader({ allowPrivateAddress, skipPreloadedContexts, userAgent } = {}) {
+    async function load(url) {
+        if (!skipPreloadedContexts && url in preloadedContexts) {
+            logger.debug("Using preloaded context: {url}.", { url });
+            return {
+                contextUrl: null,
+                document: preloadedContexts[url],
+                documentUrl: url,
+            };
+        }
+        if (!allowPrivateAddress) {
+            try {
+                await validatePublicUrl(url);
+            }
+            catch (error) {
+                if (error instanceof UrlError) {
+                    logger.error("Disallowed private URL: {url}", { url, error });
+                }
+                throw error;
+            }
+        }
+        const request = createRequest(url, { userAgent });
+        logRequest(request);
+        const response = await fetch(request, {
+            // Since Bun has a bug that ignores the `Request.redirect` option,
+            // to work around it we specify `redirect: "manual"` here too:
+            // https://github.com/oven-sh/bun/issues/10754
+            redirect: "manual",
+        });
+        // Follow redirects manually to get the final URL:
+        if (response.status >= 300 && response.status < 400 &&
+            response.headers.has("Location")) {
+            return load(response.headers.get("Location"));
+        }
+        return getRemoteDocument(url, response, load);
+    }
+    return load;
+}
+const _fetchDocumentLoader = getDocumentLoader();
+const _fetchDocumentLoader_allowPrivateAddress = getDocumentLoader({
+    allowPrivateAddress: true,
+});
 /**
  * A JSON-LD document loader that utilizes the browser's `fetch` API.
  *
@@ -138,45 +199,20 @@ async function getRemoteDocument(url, response, fetch) {
  * - <https://w3id.org/security/data-integrity/v1>
  * - <https://www.w3.org/ns/did/v1>
  * - <https://w3id.org/security/multikey/v1>
+ * - <https://purl.archive.org/socialweb/webfinger>
+ * - <http://schema.org/>
  * @param url The URL of the document to load.
  * @param allowPrivateAddress Whether to allow fetching private network
  *                            addresses.  Turned off by default.
  * @returns The remote document.
+ * @deprecated Use {@link getDocumentLoader} instead.
  */
-export async function fetchDocumentLoader(url, allowPrivateAddress = false) {
-    if (url in preloadedContexts) {
-        logger.debug("Using preloaded context: {url}.", { url });
-        return {
-            contextUrl: null,
-            document: preloadedContexts[url],
-            documentUrl: url,
-        };
-    }
-    if (!allowPrivateAddress) {
-        try {
-            await validatePublicUrl(url);
-        }
-        catch (error) {
-            if (error instanceof UrlError) {
-                logger.error("Disallowed private URL: {url}", { url, error });
-            }
-            throw error;
-        }
-    }
-    const request = createRequest(url);
-    logRequest(request);
-    const response = await fetch(request, {
-        // Since Bun has a bug that ignores the `Request.redirect` option,
-        // to work around it we specify `redirect: "manual"` here too:
-        // https://github.com/oven-sh/bun/issues/10754
-        redirect: "manual",
-    });
-    // Follow redirects manually to get the final URL:
-    if (response.status >= 300 && response.status < 400 &&
-        response.headers.has("Location")) {
-        return fetchDocumentLoader(response.headers.get("Location"), allowPrivateAddress);
-    }
-    return getRemoteDocument(url, response, (url) => fetchDocumentLoader(url, allowPrivateAddress));
+export function fetchDocumentLoader(url, allowPrivateAddress = false) {
+    logger.warn("fetchDocumentLoader() function is deprecated.  " +
+        "Use getDocumentLoader() function instead.");
+    return (allowPrivateAddress
+        ? _fetchDocumentLoader_allowPrivateAddress
+        : _fetchDocumentLoader)(url);
 }
 /**
  * Gets an authenticated {@link DocumentLoader} for the given identity.
@@ -184,13 +220,12 @@ export async function fetchDocumentLoader(url, allowPrivateAddress = false) {
  * the fetched documents.
  * @param identity The identity to get the document loader for.
  *                 The actor's key pair.
- * @param allowPrivateAddress Whether to allow fetching private network
- *                            addresses.  Turned off by default.
+ * @param options The options for the document loader.
  * @returns The authenticated document loader.
  * @throws {TypeError} If the key is invalid or unsupported.
  * @since 0.4.0
  */
-export function getAuthenticatedDocumentLoader(identity, allowPrivateAddress = false) {
+export function getAuthenticatedDocumentLoader(identity, { allowPrivateAddress, userAgent } = {}) {
     validateCryptoKey(identity.privateKey);
     async function load(url) {
         if (!allowPrivateAddress) {
@@ -204,7 +239,7 @@ export function getAuthenticatedDocumentLoader(identity, allowPrivateAddress = f
                 throw error;
             }
         }
-        let request = createRequest(url);
+        let request = createRequest(url, { userAgent });
         request = await signRequest(request, identity.privateKey, identity.keyId);
         logRequest(request);
         const response = await fetch(request, {
@@ -273,13 +308,11 @@ export function kvCache({ loader, kv, prefix, rules }) {
 }
 /**
  * Gets the user agent string for the given application and URL.
- * @param app An optional application name and version, e.g., `"Hollo/1.0.0"`.
- * @param url An optional URL to append to the user agent string.
- *            Usually the URL of the ActivityPub instance.
+ * @param options The options for making the user agent string.
  * @returns The user agent string.
  * @since 1.3.0
  */
-export function getUserAgent(app, url) {
+export function getUserAgent({ software, url } = {}) {
     const fedify = `Fedify/${metadata.version}`;
     const runtime = "Deno" in dntShim.dntGlobalThis
         ? `Deno/${dntShim.Deno.version.deno}`
@@ -289,7 +322,7 @@ export function getUserAgent(app, url) {
             : "process" in dntShim.dntGlobalThis
                 ? `Node.js/${process.version}`
                 : null;
-    const userAgent = app == null ? [fedify] : [app, fedify];
+    const userAgent = software == null ? [fedify] : [software, fedify];
     if (runtime != null)
         userAgent.push(runtime);
     if (url != null)

package/esm/sig/key.js

@@ -1,6 +1,6 @@
 import * as dntShim from "../_dnt.shims.js";
 import { getLogger } from "@logtape/logtape";
-import { fetchDocumentLoader, } from "../runtime/docloader.js";
+import { getDocumentLoader, } from "../runtime/docloader.js";
 import { isActor } from "../vocab/actor.js";
 import { CryptographicKey, Object } from "../vocab/vocab.js";
 /**
@@ -123,7 +123,7 @@ cls, { documentLoader, contextLoader, keyCache } = {}) {
     logger.debug("Fetching key {keyId} to verify signature...", { keyId });
     let document;
     try {
-        const remoteDocument = await (documentLoader ?? fetchDocumentLoader)(keyId);
+        const remoteDocument = await (documentLoader ?? getDocumentLoader())(keyId);
         document = remoteDocument.document;
     }
     catch (_) {

package/esm/sig/ld.js

@@ -4,7 +4,7 @@ import { decodeBase64, encodeBase64 } from "../deps/jsr.io/@std/encoding/1.0.5/b
 import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.5/hex.js";
 // @ts-ignore TS7016
 import jsonld from "jsonld";
-import { fetchDocumentLoader, } from "../runtime/docloader.js";
+import { getDocumentLoader, } from "../runtime/docloader.js";
 import { Activity, CryptographicKey, Object } from "../vocab/vocab.js";
 import { fetchKey, validateCryptoKey } from "./key.js";
 const logger = getLogger(["fedify", "sig", "ld"]);
@@ -200,7 +200,7 @@ export async function verifyJsonLd(jsonLd, options = {}) {
 async function hashJsonLd(jsonLd, contextLoader) {
     const canon = await jsonld.canonize(jsonLd, {
         format: "application/n-quads",
-        documentLoader: contextLoader ?? fetchDocumentLoader,
+        documentLoader: contextLoader ?? getDocumentLoader(),
     });
     const encoder = new TextEncoder();
     const hash = await dntShim.crypto.subtle.digest("SHA-256", encoder.encode(canon));

package/esm/sig/owner.js

@@ -1,4 +1,4 @@
-import { fetchDocumentLoader, } from "../runtime/docloader.js";
+import { getDocumentLoader, } from "../runtime/docloader.js";
 import { isActor } from "../vocab/actor.js";
 import { CryptographicKey, Object as ASObject, } from "../vocab/vocab.js";
 export { exportJwk, generateCryptoKeyPair, importJwk } from "./key.js";
@@ -32,8 +32,8 @@ export async function doesActorOwnKey(activity, key, options) {
  *          owner.
  */
 export async function getKeyOwner(keyId, options) {
-    const documentLoader = options.documentLoader ?? fetchDocumentLoader;
-    const contextLoader = options.contextLoader ?? fetchDocumentLoader;
+    const documentLoader = options.documentLoader ?? getDocumentLoader();
+    const contextLoader = options.contextLoader ?? getDocumentLoader();
     let object;
     if (keyId instanceof CryptographicKey) {
         object = keyId;

package/esm/vocab/actor.js

@@ -67,7 +67,7 @@ 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.
+ * @param options The extra options for getting the actor handle.
  * @returns The actor handle.  It starts with `@` and is followed by the
  *          username and domain, separated by `@` by default (it can be
  *          customized with the options).
@@ -78,7 +78,9 @@ export function getActorClassByTypeName(typeName) {
 export async function getActorHandle(actor, options = {}) {
     const actorId = actor instanceof URL ? actor : actor.id;
     if (actorId != null) {
-        const result = await lookupWebFinger(actorId);
+        const result = await lookupWebFinger(actorId, {
+            userAgent: options.userAgent,
+        });
         if (result != null) {
             const aliases = [...(result.aliases ?? [])];
             if (result.subject != null)
@@ -88,7 +90,7 @@ export async function getActorHandle(actor, options = {}) {
                 if (match != null) {
                     const hostname = new URL(`https://${match[2]}/`).hostname;
                     if (hostname !== actorId.hostname &&
-                        !await verifyCrossOriginActorHandle(actorId.href, alias)) {
+                        !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent)) {
                         continue;
                     }
                     return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
@@ -102,8 +104,8 @@ export async function getActorHandle(actor, options = {}) {
     }
     throw new TypeError("Actor does not have enough information to get the handle.");
 }
-async function verifyCrossOriginActorHandle(actorId, alias) {
-    const response = await lookupWebFinger(alias);
+async function verifyCrossOriginActorHandle(actorId, alias, userAgent) {
+    const response = await lookupWebFinger(alias, { userAgent });
     if (response == null)
         return false;
     for (const alias of response.aliases ?? []) {

package/esm/vocab/lookup.js

@@ -1,7 +1,7 @@
 import * as dntShim from "../_dnt.shims.js";
 import { getLogger } from "@logtape/logtape";
 import { delay } from "../deps/jsr.io/@std/async/1.0.8/delay.js";
-import { fetchDocumentLoader, } from "../runtime/docloader.js";
+import { getDocumentLoader, } from "../runtime/docloader.js";
 import { lookupWebFinger } from "../webfinger/lookup.js";
 import { Object } from "./vocab.js";
 const logger = getLogger(["fedify", "vocab", "lookup"]);
@@ -39,7 +39,8 @@ const handleRegexp = /^@?((?:[-A-Za-z0-9._~!$&'()*+,;=]|%[A-Fa-f0-9]{2})+)@([^@]
  * @since 0.2.0
  */
 export async function lookupObject(identifier, options = {}) {
-    const documentLoader = options.documentLoader ?? fetchDocumentLoader;
+    const documentLoader = options.documentLoader ??
+        getDocumentLoader({ userAgent: options.userAgent });
     if (typeof identifier === "string") {
         const match = handleRegexp.exec(identifier);
         if (match)
@@ -57,7 +58,9 @@ export async function lookupObject(identifier, options = {}) {
         }
     }
     if (document == null) {
-        const jrd = await lookupWebFinger(identifier);
+        const jrd = await lookupWebFinger(identifier, {
+            userAgent: options.userAgent,
+        });
         if (jrd?.links == null)
             return null;
         for (const l of jrd.links) {