lex: add more identity helpers (#2264)

* lex: add more identity helpers

* lex: update identity helpers

* make fmt

* fix typo in 'id'

* add errors; add resolveDid; more descriptions

* lint

* fix 'identifier' field names

* identity: rename def; DID deactivation as error, not flag; require handle+doc

* update again, to 'identityInfo'

* codegen

* changeset

.changeset/stale-waves-protect.md

@@ -0,0 +1,5 @@
+---
+"@atproto/api": patch
+---
+
+new com.atproto.identity endpoints: resolveDid, resolveIdentity, refreshIdentity

lexicons/com/atproto/identity/defs.json

@@ -0,0 +1,22 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.defs",
+  "defs": {
+    "identityInfo": {
+      "type": "object",
+      "required": ["did", "handle", "didDoc"],
+      "properties": {
+        "did": { "type": "string", "format": "did" },
+        "handle": {
+          "type": "string",
+          "format": "handle",
+          "description": "The validated handle of the account; or 'handle.invalid' if the handle did not bi-directionally match the DID document."
+        },
+        "didDoc": {
+          "type": "unknown",
+          "description": "The complete DID document for the identity."
+        }
+      }
+    }
+  }
+}

lexicons/com/atproto/identity/refreshIdentity.json

@@ -0,0 +1,44 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.refreshIdentity",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Request that the server re-resolve an identity (DID and handle). The server may ignore this request, or require authentication, depending on the role, implementation, and policy of the server.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["identifier"],
+          "properties": {
+            "identifier": {
+              "type": "string",
+              "format": "at-identifier"
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "ref",
+          "ref": "com.atproto.identity.defs#identityInfo"
+        }
+      },
+      "errors": [
+        {
+          "name": "HandleNotFound",
+          "description": "The resolution process confirmed that the handle does not resolve to any DID."
+        },
+        {
+          "name": "DidNotFound",
+          "description": "The DID resolution process confirmed that there is no current DID."
+        },
+        {
+          "name": "DidDeactivated",
+          "description": "The DID previously existed, but has been deactivated."
+        }
+      ]
+    }
+  }
+}

lexicons/com/atproto/identity/resolveDid.json

@@ -0,0 +1,44 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.resolveDid",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Resolves DID to DID document. Does not bi-directionally verify handle.",
+      "parameters": {
+        "type": "params",
+        "required": ["did"],
+        "properties": {
+          "did": {
+            "type": "string",
+            "format": "did",
+            "description": "DID to resolve."
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["didDoc"],
+          "properties": {
+            "didDoc": {
+              "type": "unknown",
+              "description": "The complete DID document for the identity."
+            }
+          }
+        }
+      },
+      "errors": [
+        {
+          "name": "DidNotFound",
+          "description": "The DID resolution process confirmed that there is no current DID."
+        },
+        {
+          "name": "DidDeactivated",
+          "description": "The DID previously existed, but has been deactivated."
+        }
+      ]
+    }
+  }
+}

lexicons/com/atproto/identity/resolveHandle.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Resolves a handle (domain name) to a DID.",
+      "description": "Resolves an atproto handle (hostname) to a DID. Does not necessarily bi-directionally verify against the the DID document.",
       "parameters": {
         "type": "params",
         "required": ["handle"],
@@ -25,7 +25,13 @@
             "did": { "type": "string", "format": "did" }
           }
         }
-      }
+      },
+      "errors": [
+        {
+          "name": "HandleNotFound",
+          "description": "The resolution process confirmed that the handle does not resolve to any DID."
+        }
+      ]
     }
   }
 }

lexicons/com/atproto/identity/resolveIdentity.json

@@ -0,0 +1,42 @@
+{
+  "lexicon": 1,
+  "id": "com.atproto.identity.resolveIdentity",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Resolves an identity (DID or Handle) to a full identity (DID document and verified handle).",
+      "parameters": {
+        "type": "params",
+        "required": ["identifier"],
+        "properties": {
+          "identifier": {
+            "type": "string",
+            "format": "at-identifier",
+            "description": "Handle or DID to resolve."
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "ref",
+          "ref": "com.atproto.identity.defs#identityInfo"
+        }
+      },
+      "errors": [
+        {
+          "name": "HandleNotFound",
+          "description": "The resolution process confirmed that the handle does not resolve to any DID."
+        },
+        {
+          "name": "DidNotFound",
+          "description": "The DID resolution process confirmed that there is no current DID."
+        },
+        {
+          "name": "DidDeactivated",
+          "description": "The DID previously existed, but has been deactivated."
+        }
+      ]
+    }
+  }
+}

packages/api/src/client/index.ts

@@ -20,9 +20,13 @@ import * as ComAtprotoAdminUpdateAccountEmail from './types/com/atproto/admin/up
 import * as ComAtprotoAdminUpdateAccountHandle from './types/com/atproto/admin/updateAccountHandle.js'
 import * as ComAtprotoAdminUpdateAccountPassword from './types/com/atproto/admin/updateAccountPassword.js'
 import * as ComAtprotoAdminUpdateSubjectStatus from './types/com/atproto/admin/updateSubjectStatus.js'
+import * as ComAtprotoIdentityDefs from './types/com/atproto/identity/defs.js'
 import * as ComAtprotoIdentityGetRecommendedDidCredentials from './types/com/atproto/identity/getRecommendedDidCredentials.js'
+import * as ComAtprotoIdentityRefreshIdentity from './types/com/atproto/identity/refreshIdentity.js'
 import * as ComAtprotoIdentityRequestPlcOperationSignature from './types/com/atproto/identity/requestPlcOperationSignature.js'
+import * as ComAtprotoIdentityResolveDid from './types/com/atproto/identity/resolveDid.js'
 import * as ComAtprotoIdentityResolveHandle from './types/com/atproto/identity/resolveHandle.js'
+import * as ComAtprotoIdentityResolveIdentity from './types/com/atproto/identity/resolveIdentity.js'
 import * as ComAtprotoIdentitySignPlcOperation from './types/com/atproto/identity/signPlcOperation.js'
 import * as ComAtprotoIdentitySubmitPlcOperation from './types/com/atproto/identity/submitPlcOperation.js'
 import * as ComAtprotoIdentityUpdateHandle from './types/com/atproto/identity/updateHandle.js'
@@ -254,9 +258,13 @@ export * as ComAtprotoAdminUpdateAccountEmail from './types/com/atproto/admin/up
 export * as ComAtprotoAdminUpdateAccountHandle from './types/com/atproto/admin/updateAccountHandle.js'
 export * as ComAtprotoAdminUpdateAccountPassword from './types/com/atproto/admin/updateAccountPassword.js'
 export * as ComAtprotoAdminUpdateSubjectStatus from './types/com/atproto/admin/updateSubjectStatus.js'
+export * as ComAtprotoIdentityDefs from './types/com/atproto/identity/defs.js'
 export * as ComAtprotoIdentityGetRecommendedDidCredentials from './types/com/atproto/identity/getRecommendedDidCredentials.js'
+export * as ComAtprotoIdentityRefreshIdentity from './types/com/atproto/identity/refreshIdentity.js'
 export * as ComAtprotoIdentityRequestPlcOperationSignature from './types/com/atproto/identity/requestPlcOperationSignature.js'
+export * as ComAtprotoIdentityResolveDid from './types/com/atproto/identity/resolveDid.js'
 export * as ComAtprotoIdentityResolveHandle from './types/com/atproto/identity/resolveHandle.js'
+export * as ComAtprotoIdentityResolveIdentity from './types/com/atproto/identity/resolveIdentity.js'
 export * as ComAtprotoIdentitySignPlcOperation from './types/com/atproto/identity/signPlcOperation.js'
 export * as ComAtprotoIdentitySubmitPlcOperation from './types/com/atproto/identity/submitPlcOperation.js'
 export * as ComAtprotoIdentityUpdateHandle from './types/com/atproto/identity/updateHandle.js'
@@ -766,6 +774,17 @@ export class ComAtprotoIdentityNS {
     )
   }
 
+  refreshIdentity(
+    data?: ComAtprotoIdentityRefreshIdentity.InputSchema,
+    opts?: ComAtprotoIdentityRefreshIdentity.CallOptions,
+  ): Promise<ComAtprotoIdentityRefreshIdentity.Response> {
+    return this._client
+      .call('com.atproto.identity.refreshIdentity', opts?.qp, data, opts)
+      .catch((e) => {
+        throw ComAtprotoIdentityRefreshIdentity.toKnownErr(e)
+      })
+  }
+
   requestPlcOperationSignature(
     data?: ComAtprotoIdentityRequestPlcOperationSignature.InputSchema,
     opts?: ComAtprotoIdentityRequestPlcOperationSignature.CallOptions,
@@ -778,16 +797,37 @@ export class ComAtprotoIdentityNS {
     )
   }
 
+  resolveDid(
+    params?: ComAtprotoIdentityResolveDid.QueryParams,
+    opts?: ComAtprotoIdentityResolveDid.CallOptions,
+  ): Promise<ComAtprotoIdentityResolveDid.Response> {
+    return this._client
+      .call('com.atproto.identity.resolveDid', params, undefined, opts)
+      .catch((e) => {
+        throw ComAtprotoIdentityResolveDid.toKnownErr(e)
+      })
+  }
+
   resolveHandle(
     params?: ComAtprotoIdentityResolveHandle.QueryParams,
     opts?: ComAtprotoIdentityResolveHandle.CallOptions,
   ): Promise<ComAtprotoIdentityResolveHandle.Response> {
-    return this._client.call(
-      'com.atproto.identity.resolveHandle',
-      params,
-      undefined,
-      opts,
-    )
+    return this._client
+      .call('com.atproto.identity.resolveHandle', params, undefined, opts)
+      .catch((e) => {
+        throw ComAtprotoIdentityResolveHandle.toKnownErr(e)
+      })
+  }
+
+  resolveIdentity(
+    params?: ComAtprotoIdentityResolveIdentity.QueryParams,
+    opts?: ComAtprotoIdentityResolveIdentity.CallOptions,
+  ): Promise<ComAtprotoIdentityResolveIdentity.Response> {
+    return this._client
+      .call('com.atproto.identity.resolveIdentity', params, undefined, opts)
+      .catch((e) => {
+        throw ComAtprotoIdentityResolveIdentity.toKnownErr(e)
+      })
   }
 
   signPlcOperation(