diff --git a/docs/_sidebar.md b/docs/_sidebar.md index e02080e..505fbd0 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -10,7 +10,7 @@ - [DOIP](doip.md) - [Cryptographic keys](cryptographickeys.md) - [Proofs](proofs.md) - - [Claims](claims.nd) + - [Claims](claims.md) - [Service providers](serviceproviders,md) - Service providers diff --git a/docs/api.md b/docs/api.md index fc7d158..183076a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,18 +8,35 @@ Verifies the identity behind the provided **uri** using the **fingerprint**. **Parameters** -| Name | Mandatory | Type | Description | -|-------------|-----------|--------|----------------------------------| -| uri | true | string | the URI to an identity to verify | -| fingerprint | false | string | the fingerprint of the claim | -| opts | false | object | options (see below) | +| Name | Type | Mandatory | Description | +|-------------|--------|-----------|----------------------------------| +| uri | string | true | the URI to an identity to verify | +| fingerprint | string | false | the fingerprint of the claim | +| opts | object | false | options (see below) | **Options** -| Name | Default | Type | Description | -|-------------|-----------|--------|----------------------------------| -| uri | true | string | the URI to an identity to verify | -| fingerprint | false | string | the fingerprint of the claim | -| opts | false | object | options | +| Name | Type | Default value | Description | +|-------------------|---------|----------------------|---------------------------------------------------------------------| +| returnMatchesOnly | boolean | false | only return matching service providers, do not attempt verification | +| proxyPolicy | string | 'adaptive' | when to use a proxy ['adaptive', 'always', 'never'] | +| doipProxyHostname | string | 'proxy.keyoxide.org' | the hostname of the proxy server | + +When the `proxyPolicy` option is to `adaptive`, the chosen strategy is +the one suggested by the service provider. **Returns** + +An object with the results of the identity claim verification containing a +boolean named `isVerified` and a [serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) +object. + +```json +{ + "isVerified": true, + "serviceproviderData": { ... } +} +``` + +If `opts.returnMatchesOnly` is `true`, this function instead returns a list of +service providers matched to the provided `uri`. diff --git a/docs/claims.md b/docs/claims.md index 34f417c..51933cc 100644 --- a/docs/claims.md +++ b/docs/claims.md @@ -1 +1,138 @@ # Claims + +## Definition + +A **claim** is one of the two pieces of data needed to verify an online +identity, the other being a [proof](proofs.md). + +A claim is always a phrase, string or URI that is expected to be found inside +the proof. **The presence of a claim inside a proof verifies that claim.** + +## Relation with proof + +The relation between proof and claim is defined by three variables: `format`, +`path` and `relation`. + +In the following examples, we'll assume we are dealing with a key that has the +fingerprint `13ec664f5e0c3e4ebad8b7441adbf09217175f75`. + +### format + +This variable describes how the proof is integrated in the data returned by the +service provider. + +If `format` is set to `uri`, the claim expects the proof to be or contain: + +``` +openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75 +``` + +If `format` is set to `message`, the claim expects the proof to be or contain: + +``` +[Verifying my OpenPGP key: openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75] +``` + +If `format` is set to `fingerprint`, the claim expects the proof to be or +contain: + +``` +13ec664f5e0c3e4ebad8b7441adbf09217175f75 +``` + +### path + +This variables describes how to get to the important proof-containing field +inside the JSON data. It is an array of strings, each string equal to the next +field inside the JSON data. + +If the proof data is text, the `path` value is ignored. + +Assuming the following JSON data: + +```json +"firstField": { + "secondField": { + "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75", + "yetAnotherField": "yetAnotherValue" + }, + "otherField": "someValue" +} +``` + +To verify any claim, the `path` should be set to: + +```javascript +['firstField', 'secondField', 'finalField'] +``` + +**JSON data containing arrays** + +In cases there are arrays in the JSON data, these should **not** be entered in +`path`. They will always be iterated over. + +Assuming the following JSON data: + +```json +"firstField": { + "fieldContainingArray": [ + { + "finalField": "https://domain.org", + "yetAnotherField": "yetAnotherValue1" + }, + { + "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75", + "yetAnotherField": "yetAnotherValue2" + } + ], + "otherField": "someValue" +} +``` + +To verify any claim, the `path` should be set to: + +```javascript +['firstField', 'fieldContainingArray', 'finalField'] +``` + +Every `finalField` field for every item in the `fieldContainingArray` array will +be tested for the claim. + +### relation + +This variable simply states whether after following the `path` inside the JSON +data, the obtained value `contains` the claim, `equals` the claim or if the +obtained value is an array, the claim is `oneOf` the values of the array. + +The `relation` should be `contains` for the following proof data: + +```json +"firstField": { + "secondField": { + "finalField": "Long text. openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75. Perhaps more text." + } +} +``` + +The `relation` should be `equals` for the following proof data: + +```json +"firstField": { + "secondField": { + "finalField": "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75" + } +} +``` + +The `relation` should be `oneOf` for the following proof data: + +```json +"firstField": { + "secondField": { + "finalField": [ + "cats", + "openpgp4fpr:13ec664f5e0c3e4ebad8b7441adbf09217175f75" + ] + } +} +``` diff --git a/docs/index.html b/docs/index.html index 4d9a7f3..dbac058 100644 --- a/docs/index.html +++ b/docs/index.html @@ -23,6 +23,7 @@ - + + diff --git a/docs/proofs.md b/docs/proofs.md index 5c4267d..d851fed 100644 --- a/docs/proofs.md +++ b/docs/proofs.md @@ -1 +1,25 @@ # Proofs + +## Definition + +A **proof** is one of the two pieces of data needed to verify an online +identity, the other being a [claim](claims.md). + +Usually, the proof is a JSON document provided by the service provider +containing publicly-available data of the user. This data may contain the +username and a biography. Currently, a lot of service providers are supported +because of the ability to write a proof statement inside a biography or +something similar. Other service providers are supported by entering the proof +statement in a post, in which case said service provider must provide JSON data +for each post. + +With regards to identity verification, **the presence of a claim inside a proof +verifies that claim.** + +See [claims](claims.md) for details on how proofs and claims are +(programmatically) related to each other. + +A proof can also be a text of any length. This changes nothing about the +definition above. It only means the search for the claim is simpler: no +traversing a JSON document, just find the claim inside the text and the claim is +verified. diff --git a/docs/quickstart.md b/docs/quickstart.md index 272aea9..c116e60 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,7 +2,7 @@ ## Installation -Install using **Yarn**: +Install using **yarn**: ```bash yarn add doipjs @@ -27,13 +27,13 @@ const verifyIdentity = async (url, fp) => { verifyIdentity('dns:doip.rocks', '9f0048ac0b23301e1f77e994909f6bd6f80f485d') ``` -This snippet works en will verify the [doip.rocks](https://doip.rocks) as +This snippet works en will verify the [doip.rocks](https://doip.rocks) domain as linked to Yarmo's cryptographic key using the [dns](serviceproviders/dns.md) service provider. ## Usage (browser) -Basic example: +The same code as above, but for the browser: ```html diff --git a/docs/serviceproviderdataobject.md b/docs/serviceproviderdataobject.md index 5958e37..5c33469 100644 --- a/docs/serviceproviderdataobject.md +++ b/docs/serviceproviderdataobject.md @@ -1,26 +1,34 @@ # Service provider data object +## Overview + The object returned by any service provider has the following layout: -``` -serviceprovider - type string: the service provider's type [web, communication] - name string: the service provider's name -profile - display string: the profile's identifier for display - uri string: the profile's URI -proof - uri string: the URI containing the proof to be by humans and machines - fetch string: an alternative URI that should be used by machines - useProxy boolean: should the request be sent using a proxy - format string: [json, text] -claim - fingerprint string: the fingerprint that verifies the claim if found in the proof - format string: how is the fingerprint formatted [uri, message, fingerprint] - path array: the path to the claim inside the proof JSON - relation string: how the claim format relates to the proof format [contains, equals, oneOf] -qr string: a URI to be displayed as QR code if the claim is verified -customRequestHandler function: handles the request if the default request handler does not suffice; optional +```json +{ + "serviceprovider" : { + "type": "web", + "name": "awesome-service" + }, + "profile": { + "display": "Alice", + "uri": "https://domain.org/users/Alice", + "qr": null + }, + "proof": { + "uri": "https://domain.org/users/Alice.json", + "fetch": null, + "useProxy": false, + "format": "json" + }, + "claim": { + "fingerprint": "13ec664f5e0c3e4ebad8b7441adbf09217175f75", + "format": "uri", + "path": ["user", "cryptographicKeys"], + "relation": "oneOf" + }, + "customRequestHandler": null +} ``` ## serviceprovider.type @@ -53,15 +61,106 @@ Values: * Mandatory: true ``` -The account's name to display +The account's name to display. + +## profile.uri + +``` +Type: string +Values: * +Mandatory: true +``` + +The URI/URL to the profile page of the account. + +## profile.qr + +``` +Type: string | null +Values: * +Mandatory: true +``` + +A QR link related to the profile to be displayed **if and only if** the identity proof is verified. + +## proof.uri + +``` +Type: string +Values: * +Mandatory: true +``` + +The URI to the JSON/text data that holds the proof verifying the claim. ## proof.fetch -Sometimes, the URI used by humans to verify a claim is inadequate for use by machines. This is needed when the JSON is served by a different endpoint. In this case, machines will use a different URI than the one shown to humans. +``` +Type: string | null +Values: * +Mandatory: true +``` + +If not `null`, the URI to the JSON/text data that holds the proof verifying the claim to be fetched solely by a machine. + +In some cases, we need to consider two separate URIs for proof verification. It could be that an identity proof is stored in a post. In such a case, `proof.uri` should be the URL to that post that can be verified by a human and `proof.fetch` should be the URL to the JSON data associated to that post. + +## claim.fingerprint + +``` +Type: string | null +Values: * +Mandatory: true +``` + +The fingerprint of the claim to verify against the proof. If `null`, the verification itself is skipped. ## claim.format -There are three claim formats: -- uri: the claim is formulated as `openpgp4fpr:FINGEPRPRINT` -- message: the claim is formulated as `[Verifying my OpenPGP key: openpgp4fpr:FINGEPRPRINT]` -- fingerprint: the claim is formulated as `FINGEPRPRINT` +``` +Type: string +Values: uri, message, fingerprint +Mandatory: true +``` + +The format in which the claim's fingerprint is expected to be found in the proof. There are three supported claim formats: +- `uri`: the claim is formulated as `openpgp4fpr:FINGERPRINT` +- `message`: the claim is formulated as `[Verifying my OpenPGP key: openpgp4fpr:FINGERPRINT]` +- `fingerprint`: the claim is formulated as `FINGERPRINT` + +## claim.path + +``` +Type: array | null +Values: * +Mandatory: true +``` + +The path inside the JSON proof data that leads to the field where the claim's fingerprint is expected to be found. Each field is inputted as a string appended to the array. When a certain field in the JSON data contains an array, this level will not get an input in `claim.path`: arrays are to be automatically iterated over. + +If the proof data is text based, this field is ignored and its value should be set to `null`. + +See [Claims](claims.md) for examples on how this works. + +## claim.relation + +``` +Type: string +Values: contains, equals, oneOf +Mandatory: true +``` + +How the claim relates to the proof. There are three supported claim relations: +- `contains`: the proof is a long text containing the claim +- `equals`: the proof is equal to the claim +- `oneOf`: the proof is an array of string, one of which is the claim + +## customRequestHandler + +``` +Type: function | null +Values: * +Mandatory: false +``` + +A function that will be called to handle the actual request to obtain the proof data. Most service providers will not need this and will use the default internal request handler to fetch the JSON/text data containing the proof. Service providers that need more than a single simple HTTP GET request must provide their own `customRequestHandler`.