FEDERATION.md: Write the authenticated inbox forwarding proposal

FEDERATION.md

@@ -459,6 +459,80 @@ trivial to do.
 
 #### (2) Authenticated inbox forwarding
 
+When you receive an activity from another server, by some actor A, you want to
+have some confidence that the activity was really published by actor A, and not
+by someone pretending to be actor A, or just sending you spam attributed to
+random people. This is done as follows:
+
+- You verify the HTTP Signature of the request
+- You verify the signing key's owner actor is the same actor to which the
+  activity is attributed
+
+However in some cases, such as in ForgeFed, an activity is delivered to you
+indirectly, by someone who isn't the author. Specifically, there's a mechanism
+in ActivityPub called *inbox forwarding*, in which a server receives an
+activity at an inbox, and delivers it further to more actors. For example, in
+ForgeFed, inbox forwarding is used to allow actors to address activities to
+collections managed by other servers, and those servers dereference the
+collections and forward the activity to the collection member actors.
+
+This proposal suggests a way to authenticate such inbox-forwarded activities.
+
+The concept is as follows: If Aviva sends Luke an activity, and she'd like him
+to forward it, in the HTTP POST request to his inbox, she includes an
+additional signature, in addition to the regular one. Luke uses the regular
+signature to verify the sender is really Aviva. The additional signature, he
+sends along when he forwards the activity, and the recipients use it to verify
+that:
+
+- The original author is really Aviva
+- Aviva gave Luke explicit permission to forward the activity
+
+In addition, the additional signature can be thought of as a *request* to
+forward the activity.
+
+The technical details:
+
+- The additional HTTP Signature that Aviva includes in the POST request to
+  Luke's inbox is placed in the `Forwarding-Signature`.
+- Aviva also includes a header `ActivityPub-Forwarder`, whose value is Luke's
+  ID URI.
+- The `Forwarding-Signature` signature must use at least the headers `Digest`
+  and `ActivityPub-Forwarder`.
+- When Luke receives the activity from Aviva, he notices that the
+  `ActivityPub-Forwarder` header is present, and that it's his ID URI, and that
+  `Forwarding-Signature` is present too, and he takes that as a request and
+  permission to perform inbox forwarding. He determines to whom to forward the
+  activity using the ActivityPub inbox forwarding rules, as specified in the
+  ActivityPub spec. Luke also may examine the `Forwarding-Signature`, verify
+  that the signed headers are present, and perhaps also fetch Aviva's key and
+  verify the signature.
+- Luke verifies the regular HTTP Signature in Aviva's request, and verifies the
+  `Digest` header by computing the request body hash
+- When Luke forwards the activity to other actors, he uses the exact same
+  request body that Aviva sent him, copying the bytes without any modification.
+- Luke includes in his forwarding POST requests the `Digest` header copied from
+  Aviva's request, and the `Forwarding-Actor` header copied as well, and also
+  also her additional HTTP signature, except he places that signature in the
+  `Forwarded-Signature` header, not in `Forwarding-Signature`. For the
+  signature to be successfully verified by recipients, Luke will also need to
+  copy any other headers used in the `Forwarding-Signature` that Aviva sent.
+  Unless extensions to this proposal require other specific headers, the *only*
+  headers used in the forwarding signature should be `Digest` and
+  `ActivityPub-Forwarder`. In particular, don't use `Host` and
+  `(request-target)`, because these vary per request and that will make
+  authenticated forwarding impossible.
+- Each recipient of Luke's forwarding POST tries to verify his HTTP Signature,
+  to verify that Luke is indeed the author of the activity. However the
+  recipient discovers that while Luke is the sender and his signature is valid,
+  the author is actually Aviva. The recipient then notices the
+  `Forwarded-Signature` header, which means this is a forwarded activity, and
+  that the `ActivityPub-Forwarder` is Luke, which means Aviva gave Luke
+  permission to forward this activity. The recipient then verifies the HTTP
+  Signature in the `Forwarded-Signature` header, verifying Aviva is the
+  original author and gave Luke permission to forward. The recipient then
+  proceeds to process the activity as usual.
+
 #### (3) Non-announced following
 
 #### (4) Object nesting depth