Merge pull request #626 from 2chanhaeng/main

Implement RFC 9421 §5 `Accept-Signature` challenge-response negotiation

Author: dahlia

CHANGES.md

@@ -34,10 +34,22 @@ To be released.
     caused a `500 Internal Server Error` when interoperating with servers like
     GoToSocial that have authorized fetch enabled.  [[#473], [#589]]
 
+ -  Added RFC 9421 §5 `Accept-Signature` negotiation for both outbound and
+    inbound paths.  On the outbound side, `doubleKnock()` now parses
+    `Accept-Signature` challenges from `401` responses and retries with a
+    compatible RFC 9421 signature before falling back to legacy spec-swap.
+    On the inbound side, a new `InboxChallengePolicy` option in
+    `FederationOptions` enables emitting `Accept-Signature` headers on
+    inbox `401` responses, with optional one-time nonce support for replay
+    protection.  [[#583], [#584], [#626] by ChanHaeng Lee]
+
 [#472]: https://github.com/fedify-dev/fedify/issues/472
 [#473]: https://github.com/fedify-dev/fedify/issues/473
+[#583]: https://github.com/fedify-dev/fedify/issues/583
+[#584]: https://github.com/fedify-dev/fedify/issues/584
 [#589]: https://github.com/fedify-dev/fedify/pull/589
 [#611]: https://github.com/fedify-dev/fedify/pull/611
+[#626]: https://github.com/fedify-dev/fedify/pull/626
 
 ### @fedify/vocab-runtime
 

deno.json

@@ -29,12 +29,14 @@
     "./packages/webfinger",
     "./examples/astro",
     "./examples/fresh",
-    "./examples/hono-sample"
+    "./examples/hono-sample",
+    "./examples/rfc-9421-test"
   ],
   "imports": {
     "@cloudflare/workers-types": "npm:@cloudflare/workers-types@^4.20250529.0",
     "@david/dax": "jsr:@david/dax@^0.43.2",
     "@fxts/core": "npm:@fxts/core@^1.21.1",
+    "@hongminhee/localtunnel": "jsr:@hongminhee/localtunnel@^0.3.0",
     "@js-temporal/polyfill": "npm:@js-temporal/polyfill@^0.5.1",
     "@logtape/file": "jsr:@logtape/file@^2.0.0",
     "@logtape/logtape": "jsr:@logtape/logtape@^2.0.0",

deno.lock

@@ -37,6 +37,48 @@ why some activities are rejected, you can turn on [logging](./log.md) for
 [Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/
 [FEP-8b32]: https://w3id.org/fep/8b32
 
+### `Accept-Signature` challenges
+
+*This API is available since Fedify 2.1.0.*
+
+You can optionally enable [`Accept-Signature`] challenge emission on inbox
+`401` responses by setting the `inboxChallengePolicy` option when creating
+a `Federation`:
+
+~~~~ typescript
+import { createFederation } from "@fedify/fedify";
+
+const federation = createFederation<void>({
+  // ... other options ...
+  inboxChallengePolicy: {
+    enabled: true,
+    // Optional: customize covered components (defaults shown below)
+    // components: ["@method", "@target-uri", "@authority", "content-digest"],
+    // Optional: require a one-time nonce for replay protection
+    // requestNonce: false,
+    // Optional: nonce TTL in seconds (default: 300)
+    // nonceTtlSeconds: 300,
+  },
+});
+~~~~
+
+When enabled, if HTTP Signature verification fails, the `401` response will
+include an `Accept-Signature` header telling the sender which components and
+parameters to include in a new signature.  Senders that support [RFC 9421 §5]
+(including Fedify 2.1.0+) will automatically retry with the requested
+parameters.
+
+Note that actor/key mismatch `401` responses are *not* challenged, since
+re-signing with different parameters does not resolve an impersonation issue.
+
+When `requestNonce` is enabled, a cryptographically random nonce is included
+in each challenge and must be echoed back in the retry signature.  The nonce
+is stored in the key-value store and consumed on use, providing replay
+protection.  Nonces expire after `nonceTtlSeconds` (default: 5 minutes).
+
+[`Accept-Signature`]: https://www.rfc-editor.org/rfc/rfc9421#section-5.1
+[RFC 9421 §5]: https://www.rfc-editor.org/rfc/rfc9421#section-5
+
 
 Handling unverified activities
 ------------------------------

docs/manual/inbox.md

@@ -984,6 +984,39 @@ 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
 
+### `Accept-Signature` negotiation
+
+*This API is available since Fedify 2.1.0.*
+
+In addition to double-knocking, Fedify supports the [`Accept-Signature`]
+challenge-response negotiation defined in [RFC 9421 §5].  When a recipient
+server responds with a `401` status and includes an `Accept-Signature` header,
+Fedify automatically parses the challenge, validates it, and retries the
+request with the requested signature parameters (e.g., specific covered
+components, a nonce, or a tag).
+
+Safety constraints prevent abuse:
+
+ -  The requested algorithm (`alg`) must match the local private key's
+    algorithm; otherwise the challenge entry is skipped.
+ -  The requested key identifier (`keyid`) must match the local key; otherwise
+    the challenge entry is skipped.
+ -  Fedify's minimum covered component set (`@method`, `@target-uri`,
+    `@authority`) is always included, even if the challenge does not request
+    them.
+
+If the challenge cannot be fulfilled (e.g., incompatible algorithm),
+Fedify falls through to the existing double-knocking spec-swap fallback.
+At most three signed request attempts are made to the final URL per delivery
+attempt (redirects may add extra HTTP requests):
+
+1.  Initial signed request
+2.  Challenge-driven retry (if `Accept-Signature` is present)
+3.  Legacy spec-swap retry (if the challenge retry also fails)
+
+[`Accept-Signature`]: https://www.rfc-editor.org/rfc/rfc9421#section-5.1
+[RFC 9421 §5]: https://www.rfc-editor.org/rfc/rfc9421#section-5
+
 
 Linked Data Signatures
 ----------------------

docs/manual/send.md

@@ -1,4 +1,7 @@
 {
+  "compilerOptions": {
+    "moduleResolution": "nodenext"
+  },
   "imports": {
     "@deno/astro-adapter": "npm:@deno/astro-adapter@^0.3.2"
   },

examples/astro/deno.json

@@ -0,0 +1,129 @@
+RFC 9421 interoperability field test
+====================================
+
+A Fedify-based server for testing RFC 9421 HTTP Message Signatures
+interoperability with Bonfire, Mastodon, and other fediverse implementations.
+
+
+Prerequisites
+-------------
+
+ -  [Deno] installed
+ -  Run `mise run install` (or `pnpm install`) from the repo root
+ -  A public tunnel for testing (e.g., `fedify tunnel`)
+
+[Deno]: https://deno.com/
+
+
+Quick start
+-----------
+
+### 1. start the server
+
+~~~~ sh
+# Default (RFC 9421 first knock + Accept-Signature challenge):
+deno run -A main.ts
+
+# With nonce replay protection:
+CHALLENGE_NONCE=1 deno run -A main.ts
+
+# Without challenge (plain signature verification only):
+CHALLENGE_ENABLED=0 deno run -A main.ts
+~~~~
+
+### 2. expose publicly with `fedify tunnel`
+
+In a separate terminal, from the repo root:
+
+~~~~ sh
+deno task cli tunnel 8000
+~~~~
+
+Note the public URL (e.g., `https://xxxxx.tunnel.example`).
+
+### 3. send test activities
+
+Open your browser or use curl.  Both GET (query params) and POST (JSON body)
+are supported:
+
+~~~~ sh
+# Follow a remote actor (GET):
+curl 'https://xxxxx.tunnel.example/send/follow?handle=@user@bonfire.example'
+
+# Follow a remote actor (POST):
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"handle":"@user@bonfire.example"}' \
+  https://xxxxx.tunnel.example/send/follow
+
+# Send a note:
+curl 'https://xxxxx.tunnel.example/send/note?handle=@user@bonfire.example&content=Hello!'
+
+# Unfollow:
+curl 'https://xxxxx.tunnel.example/send/unfollow?handle=@user@bonfire.example'
+~~~~
+
+
+Configuration
+-------------
+
+All configuration is via environment variables:
+
+| Variable            | Default    | Description                                                             |
+| ------------------- | ---------- | ----------------------------------------------------------------------- |
+| `PORT`              | `8000`     | Server listen port                                                      |
+| `FIRST_KNOCK`       | `rfc9421`  | Initial signature spec (`rfc9421` or `draft-cavage-http-signatures-12`) |
+| `CHALLENGE_ENABLED` | (enabled)  | Set to `0` to disable `Accept-Signature` on `401`                       |
+| `CHALLENGE_NONCE`   | (disabled) | Set to `1` to include one-time nonce                                    |
+| `NONCE_TTL`         | `300`      | Nonce time-to-live in seconds                                           |
+
+
+Endpoints
+---------
+
+### Monitoring
+
+ -  `GET /` — Server info and endpoint list
+ -  `GET /log` — Received activities (newest first)
+ -  `GET /followers-list` — Current followers
+
+### Sending activities (outbound)
+
+All send endpoints accept GET (query params) or POST (JSON body).
+
+ -  `/send/follow` — Send a Follow activity
+     -  `handle` (required): remote actor handle
+ -  `/send/note` — Send a Create(Note) activity
+     -  `handle` (required): remote actor handle
+     -  `content` (optional): note text
+ -  `/send/unfollow` — Send an Undo(Follow) activity
+     -  `handle` (required): remote actor handle
+
+
+Test scenarios
+--------------
+
+### Scenario A: Fedify -> bonfire (outbound)
+
+1.  Start the server and expose via tunnel.
+2.  Use `/send/follow` and `/send/note` to send activities to a Bonfire actor.
+3.  Check Bonfire server logs for RFC 9421 signature verification.
+
+### Scenario B: Bonfire -> Fedify (inbound with challenge)
+
+1.  Start the server with `CHALLENGE_ENABLED=1`.
+2.  Have Bonfire send a `Follow` to `@test@<your-domain>`.
+3.  Verify Fedify returns `401` with `Accept-Signature` header.
+4.  Verify Bonfire retries with a compatible signature and succeeds.
+5.  Repeat with `CHALLENGE_NONCE=1` for replay protection testing.
+
+### Scenario C: Fedify -> Mastodon (outbound)
+
+1.  Start the server and expose via tunnel.
+2.  Use `/send/follow` targeting a Mastodon actor.
+3.  Monitor logs for double-knock behavior and 5xx workaround.
+
+### Scenario D: Mastodon -> Fedify (inbound)
+
+1.  Start the server (optionally with challenge enabled).
+2.  From a Mastodon account, follow `@test@<your-domain>`.
+3.  Check the `/log` endpoint and server logs.