Overall changes + API stubs (#52)

* Define headers for migration section

* Add stubs for needed migrations routes

* Link fixes and clarifying improvements

Author: bitfl0wer

docs/APIs/core/Routes: No registration needed.md

@@ -466,6 +466,30 @@ This request has no body.
 
 ---
 
+## <span class="group-h">Migration</span>
+
+Routes concerned with identity migration and re-signing messages.
+
+---
+
+### <span class="request-h"><span class="request request-post">POST</span> Set up a redirect for migrating identities [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/redirect/extern`
+
+---
+
+### <span class="request-h"><span class="request request-get">GET</span> Request message re-signing [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/messages/extern`
+
+---
+
+### <span class="request-h"><span class="request request-post">POST</span> Commit re-signed messages [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/messages/extern`
+
+---
+
 TODO: "All challenge strings and their responses created in the context of account migration must be made public to ensure that a chain of trust can be maintained"
 
 TODO: Add routes concerned with account and data migration.
@@ -475,4 +499,3 @@ TODO: Add routes concerned with account and data migration.
 ## Glossary
 
 --8<-- "snippets/glossary.md"
-

docs/APIs/core/Routes: Registration needed.md

@@ -369,7 +369,7 @@ Remove a service from the list of services discoverable by other actors.
 
 ---
 
-### <span clas="request-h"><span class="request request-put">PUT</span> Set primary service provider [:material-lock-outline:](#authorization "Authorization required") :material-eye-lock-outline:{title="This route is considered a sensitive action."}</span>
+### <span class="request-h"><span class="request request-put">PUT</span> Set primary service provider [:material-lock-outline:](#authorization "Authorization required") :material-eye-lock-outline:{title="This route is considered a sensitive action."}</span>
 
 `/.p2/core/v1/services/primary`
 
@@ -421,6 +421,30 @@ for a given service namespace.
 
 ---
 
+## <span class="group-h">Migration</span>
+
+Routes concerned with identity migration and re-signing messages.
+
+---
+
+### <span class="request-h"><span class="request request-post">POST</span> Set up a redirect for migrating identities [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/redirect`
+
+---
+
+### <span class="request-h"><span class="request request-post">POST</span> Request enabling message re-signing (Receive key trial) [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/messages`
+
+---
+
+### <span class="request-h"><span class="request request-post">POST</span> Complete key trial [:material-lock-outline:](#authorization "Authorization required")</span>
+
+`.p2/core/v1/migration/messages/keys`
+
+---
+
 TODO: Add routes concerned with account and data migration.
 
 ---

docs/Protocol Specifications/core.md

@@ -212,18 +212,18 @@ are employed to sign messages that the actor sends to other servers.
 
 !!! note "Using one identity for several polyproto implementations"
 
-    An actor can choose to use the same identity for multiple polyproto implementations. If section
-    [4.1.3](#413-authenticating-on-a-foreign-server) is implemented correctly, this should not be a problem.
+    An actor can choose to use the same identity for multiple polyproto implementations. Read
+    [section #9](#9-services) for more information.
 
 !!! info
 
-    You can read more about the Identity Keys and Certificates in [7. Keys and signatures](#7-keys-and-signatures).
+    You can read more about Identity Certificates in [section #6.](#6-cryptography-and-id-certs)
 
 ### 4.1 Authentication
 
 The core polyproto specification does not contain a strict definition of authentication procedures
 and endpoints. This allows for a wide range of authentication methods to be used. However, if
-implementations want to closely interoperate with each other, they should **highly** consider
+implementations want to closely interoperate with each other, they should highly consider
 implementing the [polyproto-auth](./auth.md) standard for authenticating on home servers and
 foreign servers alike.
 
@@ -312,10 +312,10 @@ servers from generating federation tokens for users without their consent and kn
 
 !!! abstract
 
-    The above scenario is not unique to polyproto, and rather a problem other federated services/
-    protocols, like ActivityPub, have as well. There is no real solution to this problem, but it can
-    be mitigated a bit by making it more difficult for malicious home servers to do something like
-    this without the actor noticing.
+    The above scenario is not unique to polyproto, and rather a problem other federated
+    services/protocols, like ActivityPub, have as well. There is no real solution to this problem,
+    but it can be mitigated a bit by making it more difficult for malicious home servers to do
+    something like this without the actor noticing.
 
 Polyproto servers need to inform users of new sessions. This visibility hampers malicious home
 servers, but does not solve the issue of them being able to create federation tokens for servers the
@@ -337,7 +337,7 @@ excluding the new session. The `NEW_SESSION` event's stored data can be accessed
 ## 5. Federation IDs (FIDs)
 
 Every client requires an associated actor identity. Actors are distinguished by a unique federation
-ID (FID), consist of their identifier, which is unique per instance, and the instance's root domain.
+ID (FID). FIDs consist of their identifier, which is unique per instance, and the instance's root domain.
 This combination ensures global uniqueness.
 
 FIDs used in public contexts are formatted as `actor@optionalsubdomain.domain.tld`, and are case-insensitive.
@@ -394,7 +394,8 @@ When signing an ID-CSR, the home server must verify the correctness of all claim
     This includes checking whether the signature matches the certificates' contents and checking the
     certificate's validity period.
 
-Actors must use a separate ID-Cert for each client or session they use.
+Actors must use a separate ID-Cert for each client or session they use. Separating ID-Certs
+limits the potential damage a compromised ID-Cert can cause.
 
 For two implementations of polyproto to be interoperable, they must support an overlapping set of
 digital signature algorithms. See [Section 6.4](#64-cryptographic-recommendations) for more
@@ -529,6 +530,15 @@ Users must hold on to all of their past key pairs, as they might need them to
 [migrate their account in the future](#7-migrations). How this is done is specified in
 [section 6.3: Private key loss prevention and private key recovery](#63-private-key-loss-prevention-and-private-key-recovery).
 
+The lifetime of an actor ID-Cert should be limited to a maximum of 60 days. This is to ensure that even
+in a worst-case scenario, a compromised ID-Cert can only be used for a limited amount of time. The
+renewal of an ID-Cert is considered a [sensitive action](#412-sensitive-actions) and should require
+a second factor of authentication. A client that has this second factor of authentication stored
+should renew the ID-Cert of the authenticated actor without further interaction.
+
+Server ID-Certs should be rotated way less often (every 1-3 years). Only rotate a server ID-Cert
+if it is suspected to be compromised, is lost, or has expired.
+
 ```mermaid
 sequenceDiagram
 autonumber
@@ -748,14 +758,16 @@ should be distinguishable from signed messages at first glance.
 As described in previous sections, actors must hold on to their past identity key pairs, should they
 want or need to migrate their account.
 
-Home servers must offer a way for actors to upload and recover their private identity keys while not 
+Home servers must offer a way for actors to upload and recover their private identity keys while not
 having access to the private keys themselves. Private identity keys must be encrypted with
 strong passphrases and encryption schemes such as AES, before being uploaded to the server.
 Authenticated actors can download their encrypted private identity keys from the server at any time.
 All encryption and decryption operations must be done client-side.
 
 If any uncertainty about the availability of the home server exists, clients should regularly
 download their encrypted private identity keys from the server and store them in a secure location.
+Ideally, each client should immediately download their encrypted private identity keys from the
+server after connecting. Clients should never store key backups in an unencrypted manner.
 
 Whether an actor uploads their encrypted private identity keys to the server is their own choice.
 It is also recommended backing up the encrypted private identity keys in some other secure location.
@@ -783,9 +795,6 @@ implementing polyproto.
 
 #### 6.5.1 Signing keys and ID-Certs
 
-- Actor and client signing keys should be rotated regularly (every 20-60 days). This is to ensure
-  that a compromised key can only be used for a limited amount of time. Server identity keys should be
-  rotated way less often (every 1-5 years), and perhaps only when a leak is suspected.
 - When a server is asked to generate a new ID-Cert for an actor, it must make sure that the CSR is
   valid and, if set, has an expiry date less than or equal to the expiry date of the server's own ID-Cert.
 - Due to the fact that a `SERVER_KEY_CHANGE` gateway event is bound to generate a large amount of