From 3191452a3a9f268215257d22d9ef6f34305e72c9 Mon Sep 17 00:00:00 2001
From: fr33domlover <fr33domlover@riseup.net>
Date: Mon, 3 Jun 2019 10:38:45 +0000
Subject: [PATCH] FEDERATION.md: Write authorization token proposal

---
 FEDERATION.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/FEDERATION.md b/FEDERATION.md
index e5e72bf..f3b56e6 100644
--- a/FEDERATION.md
+++ b/FEDERATION.md
@@ -539,6 +539,90 @@ The technical details:
 
 #### (5) Object capability authorization tokens
 
+Allows actors to delegate resource access to other actors, by sending them an
+authorization token. There are many kinds of authorization tokens, and many of
+them are good relevant candidates here, for example:
+
+- OCAP-LD
+- Macaroons
+- JWT
+
+This proposal, however, describes the current implementation in Vervis, which
+uses a simple HMAC to authenticate the authorization token. Vervis on purpose
+uses a minimal approach, so that it's easy to keep track of what its minimal
+needs really are. It's totally possible and acceptable though, that this
+proposal switches to a standard auth token format such as the ones listed
+above. Until this proposal gets feedback and discussion, it describes the
+minimal HMAC approach.
+
+Aviva manages a yoga school. Luke is a new yoga teacher in the school, and
+Aviva would like to give him access to open and lock all the rooms in the
+school building. Aviva posts a `Delegate` activity to her server:
+
+```json
+{ "@context":
+    [ "https://www.w3.org/ns/activitystreams"
+    , { "ext":      "https://peers.community/as2-ext#"
+      , "Delegate": "ext:Delegate"
+      , "Role":     "ext:Role"
+      }
+    ]
+, "type":    "Delegate"
+, "to":
+    [ "https://meditation.space/users/luke"
+    , "https://yoga.dev/school-staff"
+    ]
+, "target":  "https://meditation.space/users/luke"
+, "context": "https://yoga.dev/places/school-building"
+, "object":
+    { "id":   "https://yoga.dev/roles/teacher"
+    , "type": "Role"
+    }
+}
+```
+
+Aviva's server assigns an ID to the activity, and also attaches a cryptographic
+proof. When Luke will later try to open doors in the school, the proof will be
+used to validate his authorization token. The `proof` field maps to a Base64
+encoding of the HMAC-SHA256 of the activity's ID, where the key used for the
+HMAC is a secret key the server holds.
+
+```json
+{ "@context":
+    [ "https://www.w3.org/ns/activitystreams"
+    , { "ext":      "https://peers.community/as2-ext#"
+      , "Delegate": "ext:Delegate"
+      , "Role":     "ext:Role"
+      }
+    ]
+, "id":      "https://yoga.dev/users/aviva/outbox/m10d6"
+, "type":    "Delegate"
+, "to":
+    [ "https://meditation.space/users/luke"
+    , "https://yoga.dev/school-staff"
+    ]
+, "target":  "https://meditation.space/users/luke"
+, "context": "https://yoga.dev/places/school-building"
+, "object":
+    { "id":   "https://yoga.dev/roles/teacher"
+    , "type": "Role"
+    }
+, "proof":   "bDMCcPFntgpMoEG6SSFkXCBRm2K96h0ecFsbr11hFx0="
+}
+```
+
+Later, when Luke wants to open a door, he publishes an activity and attaches
+the `proof` field. Aviva's server then:
+
+- Verifies the HMAC
+- Finds the Delegation in the database
+- Finds out that delegation gives Luke access as a teacher
+- Verifies the HTTP Signature of the activity, thus verifying the sender is
+  indeed Luke
+- Checks that the door Luke wants to open can be opened by people holding a
+  teacher role
+- If all checks pass, Luke can open the door
+
 #### (6) Managing actor
 
 Allows an object to specify which actor manages it. For example, if you'd like