Tyleryasaka/attestations and users

source/includes/resources/attestations.md

@@ -0,0 +1,161 @@
+# Attestation
+
+An **Attestation** is a confirmation that some piece of identity information has been verified by a trusted 3rd party.
+
+Origin provides an attestation service that users can optionally use to add attestations to their profile.
+
+The following attestations are currently offered:
+
+ - Email
+ - Phone
+ - Facebook
+ - Twitter
+
+Currently, attestation is simply a public *confirmation* that something has been verified by Origin.
+The information itself is not made public.
+
+For example, when a user adds an email attestation to their profile, all that anyone else will be able to see is that their email has been verified by Origin.
+The email address itself remains private.
+
+Note that these methods are used to simply generate attestation objects.
+Once an attestation object has been created, it needs to be added to a user object for it to take effect.
+
+## phoneGenerateCode
+
+> To send an SMS verification code
+
+```javascript
+await origin.attestations.phoneGenerateCode({
+  phone: "555-555-5555"
+})
+```
+
+This will send a text to the given phone number containing a verification code.
+
+## phoneVerify
+
+> To verify a ownership of a phone number
+
+```javascript
+let phoneAttestation = await origin.attestations.phoneVerify({
+  wallet: myWalletAddress,
+  phone: "555-555-5555",
+  code: "123456"
+})
+// Returns (attestation object)
+{
+  signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+  data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+  claimType: 10,
+  service: "phone"
+}
+```
+
+This will verify that the `code` submitted in the request is the one that was sent to the phone number in the `phoneGenerateCode` call. If it is valid, an attestation object will be returned.
+
+## emailGenerateCode
+
+> To send an email verification code
+
+```javascript
+await origin.attestations.emailGenerateCode({
+  email: "me@my.domain"
+})
+```
+
+This will send an email to the given email address containing a verification code.
+
+## emailVerify
+
+> To verify ownership of an email address
+
+```javascript
+let emailAttestation = await origin.attestations.emailVerify({
+  wallet: myWalletAddress,
+  email: "me@my.domain",
+  code: "123456"
+})
+// Returns (attestation object)
+{
+  signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+  data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+  claimType: 11,
+  service: "email"
+}
+```
+
+This will verify that the `code` submitted in the request is the one that was sent to the email address in the `emailGenerateCode` call. If it is valid, an attestation object will be returned.
+
+## facebookAuthUrl
+
+> To get Facebook authentication url
+
+```javascript
+await origin.attestations.facebookAuthUrl({
+  redirectUrl: "http://redirect.url"
+})
+// Returns
+"http://foo.bar"
+```
+
+This will return a url which your dapp can redirect the user to.
+The page will ask the user to grant permissions to the Origin app, which will be used to verify their Facebook identity.
+The user will be redirected to the specified `redirectUrl` after authentication. See the [Facebook login documentation](https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow) for more details.
+
+## facebookVerify
+
+> To verify ownership of a Facebook account
+
+```javascript
+let facebookAttestation = await origin.attestations.facebookVerify({
+  wallet: myWalletAddress,
+  redirectUrl: "http://redirect.url"
+  code: "12345"
+})
+// Returns (attestation object)
+{
+  signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+  data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+  claimType: 3,
+  service: "facebook"
+}
+```
+
+This will perform Facebook oauth verification on the specified `code` and `redirectUrl`. If it is valid, an attestation object will be returned.
+
+Note that `code` is the oauth code generated in `facebookAuthUrl` (it will be added as a query param the url when the user is redirected - see the [documentation](https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow) for details). `redirectUrl` *must* match the `redirectUrl` specified in the `facebookAuthUrl` call.
+
+## twitterAuthUrl
+
+> To get Twitter authentication url
+
+```javascript
+await origin.attestations.twitterAuthUrl()
+// Returns
+"http://foo.bar"
+```
+
+This will return a url which your dapp can redirect the user to.
+The page will ask the user to grant permissions to the Origin app, which will be used to verify their Twitter identity. See the [Twitter authentication documentation](https://developer.twitter.com/en/docs/basics/authentication/guides/access-tokens) for more details.
+
+## twitterVerify
+
+> To verify ownership of a Twitter account
+
+```javascript
+let twitterAttestation = await origin.attestations.twitterVerify({
+  wallet: myWalletAddress,
+  oauthVerifier: "12345"
+})
+// Returns (attestation object)
+{
+  signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+  data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+  claimType: 4,
+  service: "twitter"
+}
+```
+
+This will perform Twitter oauth verification on the specified `oauthVerifier`. If it is valid, an attestation object will be returned.
+
+Note that `oauthVerifier` is the oauth verifier code generated in `twitterAuthUrl` (it will be added as a query param the url when the user is redirected - see the [documentation](https://developer.twitter.com/en/docs/basics/authentication/guides/access-tokens) for details).

source/includes/resources/users.md

@@ -0,0 +1,107 @@
+# User
+
+A **User** is an object used to represent a particular user in Origin Protocol.
+Users are implemented as [ERC725 identities](https://medium.com/originprotocol/managing-identity-with-a-ui-for-erc-725-5c7422b38c09). Identities in Origin will be portable across platforms that support ERC725.
+
+A user object consists of 2 properties:
+
+- `profile`: Profile information a user chooses to reveal publicly
+- `attestations`: A list of 3rd party attestations that the user has added to their identity (see [Attestation documentation](#attestation) for details)
+
+## set
+
+> To create/update a user
+
+```javascript
+// Get a phone attestation object
+await origin.attestations.phoneGenerateCode({
+  phone: "555-555-5555"
+})
+let phoneAttestation = await origin.attestations.phoneVerify({
+  wallet: myWalletAddress,
+  phone: "555-555-5555",
+  code: "123456"
+})
+
+// Get a Facebook attestation object
+await origin.attestations.facebookAuthUrl({
+  redirectUrl: "http://redirect.url"
+})
+// (do some stuff to guide user through Facebook auth flow here)
+let facebookAttestation = await origin.attestations.facebookVerify({
+  wallet: myWalletAddress,
+  redirectUrl: "http://redirect.url"
+  code: "12345"
+})
+
+let myNewUser = {
+  profile: { claims: { name: "Wonder Woman" } },
+  attestations: [ phoneAttestation, facebookAttestation ]
+}
+let createdUser = await origin.users.set(myNewUser)
+
+// User has been created!
+
+// Get an email attestation object
+await origin.attestations.emailGenerateCode({
+  email: "me@my.domain"
+})
+let emailAttestation = await origin.attestations.emailVerify({
+  wallet: myWalletAddress,
+  email: "me@my.domain",
+  code: "123456"
+})
+
+createdUser.attestations.push(emailAttestation)
+let updatedUser = await origin.users.set(createdUser)
+
+// User has been updated!
+// final `updatedUser`:
+{
+  {
+    profile: { claims: { name: "Wonder Woman" } },
+    attestations: [
+      {
+        signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+        data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+        claimType: 10,
+        service: "phone"
+      },
+      {
+        signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+        data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+        claimType: 3,
+        service: "facebook"
+      },
+      {
+        signature: "0xeb6123e537e17e2c67b67bbc0b93e6b25ea9eae276c4c2ab353bd7e853ebad2446cc7e91327f3737559d7a9a90fc88529a6b72b770a612f808ab0ba57a46866e1c",
+        data: "0x7f5e752d19fee44e13bb0cc820255017c35584caddc055641d6ccadfa3afca01",
+        claimType: 4,
+        service: "twitter"
+      }
+    ]
+  }
+}
+```
+
+If the user does not already exist, it will be created. If it exists, it will be updated.
+
+**Note**: this method should be used as if it will completely override the existing data.
+Updates should be made by taking the existing user object, making modifications to it, and then passing the entire updated object into the `set` method.
+
+## get
+
+> To retrieve a user
+
+```javascript
+let myUser = await origin.users.get()
+let anotherUser = await origin.users.get(otherUserAddress)
+// Returns (user object)
+{
+  profile: {}
+  attestations: []
+}
+```
+
+With no parameters passed in, this will return the current user.
+If a wallet address is passed in, this will return the user associated with that wallet.

source/index.html.md

@@ -13,11 +13,13 @@ includes:
   - architecture
   - getting_started
   - authentication_identity
+  - resources/attestations
   - resources/listings
   - resources/purchases
+  - resources/users
   - listing_schemas
   - getting_help
   - contributing
 
 search: true
----
+---