Merge branch 'rfc9421'

Author: dahlia

.gitignore

@@ -3,3 +3,5 @@ deno.lock
 repomix-output.xml
 t.ts
 t2.ts
+
+**/.claude/settings.local.json

CHANGES.md

@@ -22,6 +22,23 @@ To be released.
 
  -  Added `Router.trailingSlashInsensitive` property.
 
+ -  Implemented HTTP Message Signatures ([RFC 9421]) with double-knocking.
+    Currently, it only works with RSA-PKCS#1-v1.5.  [[#208]]
+
+     -  Added `HttpMessageSignaturesSpec` type.
+     -  Added `SignRequestOptions.spec` option.
+     -  Added `SignRequestOptions.currentTime` option.
+     -  Added `VerifyRequestOptions.spec` option.
+     -  Added `GetAuthenticatedDocumentLoaderOptions.specDeterminer` option.
+     -  Added `GetAuthenticatedDocumentLoaderOptions.traceProvider` option.
+     -  Added `HttpMessageSignaturesSpecDeterminer` interface.
+     -  Added `--first-knock` option to `fedify lookup` command.
+
+ -  The `exportJwk()` function now populates the `alg` property of a returned
+    `JsonWebKey` object with `"Ed25519"` if the input key is an Ed25519 key.
+
+[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
+[#208]: https://github.com/fedify-dev/fedify/issues/208
 [#227]: https://github.com/fedify-dev/fedify/issues/227
 
 

cli/lookup.ts

@@ -1,5 +1,5 @@
 import { colors } from "@cliffy/ansi";
-import { Command } from "@cliffy/command";
+import { Command, EnumType } from "@cliffy/command";
 import {
   Application,
   Collection,
@@ -22,14 +22,23 @@ import { printJson } from "./utils.ts";
 
 const logger = getLogger(["fedify", "cli", "lookup"]);
 
+const sigSpec = new EnumType(["draft-cavage-http-signatures-12", "rfc9421"]);
+
 export const command = new Command()
+  .type("sig-spec", sigSpec)
   .arguments("<...urls:string>")
   .description(
     "Lookup an Activity Streams object by URL or the actor handle.  " +
       "The argument can be either a URL or an actor handle " +
       "(e.g., @username@domain), and it can be multiple.",
   )
   .option("-a, --authorized-fetch", "Sign the request with an one-time key.")
+  .option(
+    "--first-knock <spec:sig-spec>",
+    "The first-knock spec for -a/--authorized-fetch.  It is used for " +
+      "the double-knocking technique.",
+    { depends: ["authorized-fetch"], default: "rfc9421" },
+  )
   .option(
     "-t, --traverse",
     "Traverse the given collection to fetch all items.  If it is turned on, " +
@@ -118,10 +127,21 @@ export const command = new Command()
           { contextLoader },
         );
       });
-      authLoader = getAuthenticatedDocumentLoader({
-        keyId: new URL("#main-key", server.url),
-        privateKey: key.privateKey,
-      });
+      authLoader = getAuthenticatedDocumentLoader(
+        {
+          keyId: new URL("#main-key", server.url),
+          privateKey: key.privateKey,
+        },
+        {
+          specDeterminer: {
+            determineSpec() {
+              return options.firstKnock;
+            },
+            rememberSpec() {
+            },
+          },
+        },
+      );
     }
     spinner.text = `Looking up the ${
       options.traverse ? "collection" : urls.length > 1 ? "objects" : "object"
@@ -255,3 +275,5 @@ export const command = new Command()
       Deno.exit(1);
     }
   });
+
+// cSpell: ignore sigspec

cli/mod.ts

@@ -1,5 +1,6 @@
 import { Command, CompletionsCommand, HelpCommand } from "@cliffy/command";
 import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { DEFAULT_CACHE_DIR, setCacheDir } from "./cache.ts";
 import metadata from "./deno.json" with { type: "json" };
 import { command as inbox } from "./inbox.tsx";
@@ -46,6 +47,7 @@ const command = new Command()
           },
         ],
         reset: true,
+        contextLocalStorage: new AsyncLocalStorage(),
       });
     },
   })

cspell.json

@@ -23,6 +23,7 @@
     "dereferenceable",
     "discoverability",
     "docloader",
+    "draft-cavage",
     "eddsa",
     "fanout",
     "federatable",

deno.json

@@ -24,6 +24,7 @@
     "check": "deno task -f @fedify/fedify check && deno task -f @fedify/cli check && deno task -f @fedify/blog check && deno task -f @fedify/hono-sample check",
     "test-all": "deno task -f @fedify/fedify test-all && deno task -f @fedify/cli check && deno task -f @fedify/blog check && deno task -f @fedify/hono-sample check",
     "publish": "deno task -f @fedify/fedify publish && deno task -f @fedify/cli publish",
+    "cli": "deno task -f @fedify/cli run",
     "hooks:install": "deno run --allow-read=deno.json,.git/hooks/ --allow-write=.git/hooks/ jsr:@hongminhee/deno-task-hooks",
     "hooks:pre-commit": {
       "dependencies": [

docs/cli.md

@@ -727,6 +727,36 @@ Person {
 }
 ~~~~
 
+### `--first-knock`: First-knock spec for `-a`/`--authorized-fetch`
+
+*This option is available since Fedify 1.6.0.*
+
+The `--first-knock` option is used to specify which HTTP Signatures spec to
+try first when using the `-a`/`--authorized-fetch` option.  The ActivityPub
+ecosystem currently uses different versions of HTTP Signatures specifications,
+and the [double-knocking] technique (trying one version, then falling back to
+another if rejected) allows for better compatibility across servers.
+
+Available options are:
+
+`draft-cavage-http-signatures-12`
+:   [HTTP Signatures], which is obsolete but still widely adopted in
+    the fediverse as of May 2025.
+
+`rfc9421` (default)
+:   [RFC 9421]: HTTP Message Signatures, which is the final revision of
+    the specification and is recommended, but not yet widely adopted
+    in the fediverse as of May 2025.
+
+If the first signature attempt fails, Fedify will automatically try the other
+specification format, implementing the [double-knocking] technique described in
+the [ActivityPub HTTP Signatures] specification.
+
+[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions
+[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12
+[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
+[ActivityPub HTTP Signatures]: https://swicg.github.io/activitypub-http-signature/
+
 ### `-u`/`--user-agent`: Custom `User-Agent` header
 
 *This option is available since Fedify 1.3.0.*

docs/manual/federation.md

@@ -83,6 +83,16 @@ that the `Federation` object uses:
     The key prefix used for caching public keys.  `["_fedify", "publicKey"]`
     by default.
 
+`~FederationKvPrefixes.httpMessageSignaturesSpec`
+:   *This API is available since Fedify 1.6.0.*
+
+    The key prefix used for caching HTTP Message Signatures spec.  The cached
+    spec is used to reduce the number of attempts to make signed requests
+    ([double-knocking] technique).
+    `["_fedify", "httpMessageSignaturesSpec"]` by default.
+
+[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions
+
 ### `queue`
 
 *This API is available since Fedify 0.5.0.*

docs/manual/inbox.md

@@ -15,6 +15,28 @@ handle incoming activities from other actors.
 [inbox]: https://www.w3.org/TR/activitypub/#inbox
 
 
+Signature verification
+----------------------
+
+The inbox listeners automatically verify the signature of the incoming
+activities with various specifications, such as:
+
+ -  Draft cavage [HTTP Signatures]
+ -  HTTP Message Signatures ([RFC 9421])
+ -  [Linked Data Signatures]
+ -  Object Integrity Proofs ([FEP-8b32])
+
+You don't mind about the signature verification at all—unsigned activities and
+invalid signatures are silently ignored.  If you want to see why some activities
+are ignored, you can turn on [logging](./log.md) for `["fedify", "sig"]`
+category.
+
+[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12
+[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
+[Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/
+[FEP-8b32]: https://w3id.org/fep/8b32
+
+
 Registering an inbox listener
 -----------------------------
 
@@ -555,3 +577,5 @@ for await (const item of context.traverseCollection(collection)) {
 >  -  The `Activity` is dereferenceable by its `~Object.id` and
 >     the dereferenced object has an actor that belongs to the same origin
 >     as the `Activity` object.
+
+<!-- cSpell: ignore cavage -->

docs/manual/send.md

@@ -745,16 +745,66 @@ const federation = createFederation({
 HTTP Signatures
 ---------------
 
-[HTTP Signatures] is a de facto standard for signing ActivityPub activities.
-It is widely used in the fediverse to verify the sender's identity and
-the integrity of the activity.
+Draft cavage [HTTP Signatures] is a de facto standard for signing ActivityPub
+activities.  Although it is not a finalized specification, it is still widely
+used in the fediverse to verify the sender's identity and the integrity of
+the activity.
 
 Fedify automatically signs activities with the sender's private key if
 the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and
 the actor has any RSA-PKCS#1-v1.5 key pair.  If there are multiple key pairs,
 Fedify selects the first RSA-PKCS#1-v1.5 key pair among them.
 
-[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures
+[HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12
+
+
+HTTP Message Signatures
+-----------------------
+
+*This API is available since Fedify 1.6.0.*
+
+[RFC 9421], also known as *HTTP Message Signatures*, is the final revision of
+the HTTP Signatures specification.  Although it is the official standard,
+it is not widely used in the fediverse yet.  As of May 2025, major ActivityPub
+implementations, such as Mastodon, et al., still rely on the draft cavage
+version of HTTP Signatures for signing portable activities.
+
+Fedify automatically signs activities with the sender's private key if
+the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and
+the actor has any RSA-PKCS#1-v1.5 key pair.  If there are multiple key pairs,
+Fedify selects the first RSA-PKCS#1-v1.5 key pair among them.
+
+> [!NOTE]
+> Although HTTP Message Signatures support other than RSA-PKCS#1-v1.5,
+> Fedify currently supports only RSA-PKCS#1-v1.5 key pairs for generating
+> HTTP Message Signatures.  This limitation will be lifted in the future
+> releases.
+
+[RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
+
+
+Double-knocking HTTP Signatures
+-------------------------------
+
+*This API is available since Fedify 1.6.0.*
+
+As you read above, there are two revisions of HTTP Signatures:
+the [draft cavage][HTTP Signatures] version and the [RFC 9421] version.
+The draft cavage version is declared as obsolete, but it is still widely used
+in the fediverse, and many ActivityPub implementations still rely on it.
+On the other hand, the RFC 9421 version is the official standard, but
+it is not widely used yet.
+
+To support both versions of HTTP Signatures, Fedify uses the [double-knocking]
+mechanism: trying one version, then falling back to another if rejected.
+If it's the first encounter with the recipient server, Fedify tries
+the RFC 9421 version first, and if it fails, it falls back to the draft
+cavage version.  If the recipient server accepts the RFC 9421 version,
+Fedify remembers it and uses the RFC 9421 version for the next time.
+If the recipient server rejects the RFC 9421 version, Fedify falls back
+to the draft cavage version and remembers it for the next time.
+
+[double-knocking]: https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions
 
 
 Linked Data Signatures
@@ -914,3 +964,5 @@ new Follow({
 ~~~~
 
 [Threads]: https://www.threads.net/
+
+<!-- cSpell: ignore cavage -->