Account migration schemas (#2170)

* draft of account migration lexicons

* format

* clean up schemas

* second pass on schemas

* small fix

* move around checkImportStatus

* getServiceAuth

* schema tweaks

* format

* update schemas

* email flow for signed plc operation

* refactor listMissingBlobs a bit

* codegen

* return did in describeServer

* changeset

.changeset/slimy-games-breathe.md

@@ -0,0 +1,5 @@
+---
+'@atproto/api': minor
+---
+
+Add lexicons and methods for account migration

lexicons/com/atproto/identity/getRecommendedDidCredentials.json

@@ -0,0 +1,29 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.getRecommendedDidCredentials",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Describe the credentials that should be included in the DID doc of an account that is migrating to this service.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "rotationKeys": {
+              "description": "Recommended rotation keys for PLC dids. Should be undefined (or ignored) for did:webs.",
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "alsoKnownAs": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "verificationMethods": { "type": "unknown" },
+            "services": { "type": "unknown" }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/identity/requestPlcOperationSignature.json

@@ -0,0 +1,10 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.requestPlcOperationSignature",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Request an email with a code to in order to request a signed PLC operation. Requires Auth."
+    }
+  }
+}

lexicons/com/atproto/identity/signPlcOperation.json

@@ -0,0 +1,45 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.signPlcOperation",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Signs a PLC operation to update some value(s) in the requesting DID's document.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "token": {
+              "description": "A token received through com.atproto.identity.requestPlcOperationSignature",
+              "type": "string"
+            },
+            "rotationKeys": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "alsoKnownAs": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "verificationMethods": { "type": "unknown" },
+            "services": { "type": "unknown" }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["operation"],
+          "properties": {
+            "operation": {
+              "type": "unknown",
+              "description": "A signed DID PLC operation."
+            }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/identity/submitPlcOperation.json

@@ -0,0 +1,20 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.submitPlcOperation",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Validates a PLC operation to ensure that it doesn't violate a service's constraints or get the identity into a bad state, then submits it to the PLC registry",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["operation"],
+          "properties": {
+            "operation": { "type": "unknown" }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/repo/importRepo.json

@@ -0,0 +1,13 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.repo.importRepo",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Import a repo in the form of a CAR file. Requires Content-Length HTTP header to be set.",
+      "input": {
+        "encoding": "application/vnd.ipld.car"
+      }
+    }
+  }
+}

lexicons/com/atproto/repo/listMissingBlobs.json

@@ -0,0 +1,44 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.repo.listMissingBlobs",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Returns a list of missing blobs for the requesting account. Intended to be used in the account migration flow.",
+      "parameters": {
+        "type": "params",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 500
+          },
+          "cursor": { "type": "string" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["blobs"],
+          "properties": {
+            "cursor": { "type": "string" },
+            "blobs": {
+              "type": "array",
+              "items": { "type": "ref", "ref": "#recordBlob" }
+            }
+          }
+        }
+      }
+    },
+    "recordBlob": {
+      "type": "object",
+      "required": ["cid", "recordUri"],
+      "properties": {
+        "cid": { "type": "string", "format": "cid" },
+        "recordUri": { "type": "string", "format": "at-uri" }
+      }
+    }
+  }
+}

lexicons/com/atproto/server/activateAccount.json

@@ -0,0 +1,10 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.server.activateAccount",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Activates a currently deactivated account. Used to finalize account migration after the account's repo is imported and identity is setup."
+    }
+  }
+}

lexicons/com/atproto/server/checkAccountStatus.json

@@ -0,0 +1,38 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.server.checkAccountStatus",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Returns the status of an account, especially as pertaining to import or recovery. Can be called many times over the course of an account migration. Requires auth and can only be called pertaining to oneself.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": [
+            "activated",
+            "validDid",
+            "repoCommit",
+            "repoRev",
+            "repoBlocks",
+            "indexedRecords",
+            "privateStateValues",
+            "expectedBlobs",
+            "importedBlobs"
+          ],
+          "properties": {
+            "activated": { "type": "boolean" },
+            "validDid": { "type": "boolean" },
+            "repoCommit": { "type": "string", "format": "cid" },
+            "repoRev": { "type": "string" },
+            "repoBlocks": { "type": "integer" },
+            "indexedRecords": { "type": "integer" },
+            "privateStateValues": { "type": "integer" },
+            "expectedBlobs": { "type": "integer" },
+            "importedBlobs": { "type": "integer" }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/server/deactivateAccount.json

@@ -0,0 +1,23 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.server.deactivateAccount",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Deactivates a currently active account. Stops serving of repo, and future writes to repo until reactivated. Used to finalize account migration with the old host after the account has been activated on the new host.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "deleteAfter": {
+              "type": "string",
+              "format": "datetime",
+              "description": "A recommendation to server as to how long they should hold onto the deactivated account before deleting."
+            }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/server/describeServer.json

@@ -9,7 +9,7 @@
         "encoding": "application/json",
         "schema": {
           "type": "object",
-          "required": ["availableUserDomains"],
+          "required": ["did", "availableUserDomains"],
           "properties": {
             "inviteCodeRequired": {
               "type": "boolean",
@@ -28,6 +28,10 @@
               "type": "ref",
               "description": "URLs of service policy documents.",
               "ref": "#links"
+            },
+            "did": {
+              "type": "string",
+              "format": "did"
             }
           }
         }

lexicons/com/atproto/server/getServiceAuth.json

@@ -0,0 +1,33 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.server.getServiceAuth",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Get a signed token on behalf of the requesting DID for the requested service.",
+      "parameters": {
+        "type": "params",
+        "required": ["aud"],
+        "properties": {
+          "aud": {
+            "type": "string",
+            "format": "did",
+            "description": "The DID of the service that the token will be used to authenticate with"
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["token"],
+          "properties": {
+            "token": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}