Mirrors/doipjs
1
0
Fork 1
mirror of https://codeberg.org/keyoxide/doipjs.git synced 2024-12-22 22:49:28 -07:00
Code Issues Projects Releases Packages Wiki Activity

WIP Add docs

Browse source
This commit is contained in:
Yarmo Mackenbach 2020-11-06 03:39:36 +01:00
parent ea97e140bb
commit 21c72f63e2
7 changed files with 318 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/_sidebar.md
View file

@ -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

37
docs/api.md
View file

@ -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`.

137
docs/claims.md
View file

@ -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"
]
}
}
```

3
docs/index.html
View file

@ -23,6 +23,7 @@
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-json.min.js"></script>
</body>
</html>

24
docs/proofs.md
View file

@ -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.

6
docs/quickstart.md
View file

@ -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
<script src="https://cdn.jsdelivr.net/npm/keyoxide@0.3.0/dist/doip.min.js"></script>

149
docs/serviceproviderdataobject.md
View file

@ -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`.