diff --git a/source/includes/resources/attestations.md b/source/includes/resources/attestations.md new file mode 100644 index 0000000..08ad13f --- /dev/null +++ b/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). diff --git a/source/includes/resources/users.md b/source/includes/resources/users.md new file mode 100644 index 0000000..6ac3c3c --- /dev/null +++ b/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. diff --git a/source/index.html.md b/source/index.html.md index 835286d..e0ec798 100644 --- a/source/index.html.md +++ b/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 ---- \ No newline at end of file +---