WIP Update docs

docs/_coverpage.md

@@ -1,4 +1,4 @@
-# doip.js <small>0.11.2</small>
+# doip.js <small>0.12.0</small>
 
 <img src="doip.png" width="120">
 

docs/_sidebar.md

@@ -5,11 +5,6 @@
   - [Quick start (browser)](quickstart-browser.md)
   - [Terminology](terminology.md)
 
-- Reference
-
-  - [API](api.md)
-  - [Service provider data object](serviceproviderdataobject.md)
-
 - Concepts
 
   - [DOIP](doip.md)
@@ -17,6 +12,11 @@
   - [Claims](claims.md)
   - [Service providers](serviceproviders.md)
 
+- Reference doip.js
+
+  - [Claim (class)](doipjs/class_claim.md)
+  - [keys (module)](doipjs/module_keys.md)
+
 - Service providers
 
   - [dev.to](serviceproviders/devto.md)

docs/doipjs/class_claim.md

@@ -0,0 +1,129 @@
+# Claim (class)
+
+## Constructor
+
+new Claim([uri], [fingerprint])
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                       |
+| ----------- | ------ | --------- | --------------------------------- |
+| uri         | string | false     | The URI to an identity to verify  |
+| fingerprint | string | false     | The fingerprint to verify against |
+
+## Properties
+
+### uri
+
+The `uri` to an identity to verify. It can be modified until the claim is in a
+`matched` state.
+
+**Returns** `{String|null}`
+
+### fingerprint
+
+The `fingerprint` to verify against. It can be modified until the claim is in a 
+`verified` state.
+
+**Returns** `{String|null}`
+
+### state
+
+The current `state` of the Claim object. It can not be set.
+
+**Values**
+
+| Value    | Description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| init     | The claim has just been initialized                               |
+| matched  | The claim has been matched to candidate claim definitions         |
+| verified | The claim has attempted to verify all candidate claim definitions |
+
+**Returns** `{String}` The current state
+
+### matches
+
+The `matches` (or "candidate claim definitions") that have been matched against
+the `uri`.
+
+Will throw an error if the claim has not yet run `match()`.
+
+**Returns** `{Array<Object>}`
+
+## Methods
+
+### match()
+
+claimInstance.match()
+
+Verifies the identity behind the provided **uri** using the **fingerprint**.
+
+**Parameters**
+
+| 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               | 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', 'fallback', 'always', 'never']        |
+| doipProxyHostname  | string  | 'proxy.keyoxide.org' | the hostname of the proxy server                                       |
+| twitterBearerToken | string  | ''                   | the Twitter API bearer token used for Twitter verification             |
+| nitterInstance     | string  | ''                   | the domain name of the nitter instance to use for Twitter verification |
+
+When the `proxyPolicy` option is to `adaptive`, the chosen strategy is
+the one suggested by the service provider.
+
+By default, Twitter accounts are not verified. Either provide a
+[Twitter bearer token](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens)
+(as `twitterBearerToken`) or the domain name of a Nitter instance (as
+`nitterInstance`) to enable Twitter account verification. If both values are
+provided, only the Twitter bearer token is used.
+
+Note that Nitter instances are subject to rate limiting which would instantly
+break Twitter account verification.
+
+**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`.
+
+### verify([opts])
+
+_(async)_ `claimInstance.verify([opts])`
+
+Verifies the identity behind the provided **array of uris** using the **fingerprint**.
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                  |
+| ----------- | ------ | --------- | ---------------------------- |
+| uriArray    | array  | true      | array of uris                |
+| fingerprint | string | false     | the fingerprint of the claim |
+| opts        | object | false     | options (see below)          |
+
+**Options**
+
+See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
+
+**Returns**
+
+An array of objects with claim verification results (see
+[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)).

docs/doipjs/module_keys.md

@@ -1,8 +1,19 @@
-# API
+# keys (module)
 
-## claims.verify(uri, [fingerprint], [opts])
+## Constructor
 
-_(async)_ doip.claims.verify(uri, [fingerprint], [opts])
+new Claim([uri], [fingerprint])
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                      |
+| ----------- | ------ | --------- | -------------------------------- |
+| uri         | string | false     | the URI to an identity to verify |
+| fingerprint | string | false     | the fingerprint of the claim     |
+
+## Properties
+
+## Methods
 
 Verifies the identity behind the provided **uri** using the **fingerprint**.
 
@@ -53,7 +64,7 @@ object.
 If `opts.returnMatchesOnly` is `true`, this function instead returns a list of
 service providers matched to the provided `uri`.
 
-## claims.verify(uriArray, [fingerprint], [opts])
+### claims.verify(uriArray, [fingerprint], [opts])
 
 _(async)_ doip.claims.verify(array, [fingerprint], [opts])
 
@@ -76,7 +87,7 @@ See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
 An array of objects with claim verification results (see
 [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)).
 
-## claims.verify(key, [fingerprint], [opts])
+### claims.verify(key, [fingerprint], [opts])
 
 _(async)_ doip.claims.verify(key, [fingerprint], [opts])
 
@@ -101,7 +112,7 @@ See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
 An array of objects with claim verification results (see
 [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)).
 
-## keys.fetch.uri(uri)
+### keys.fetch.uri(uri)
 
 _(async)_ keys.fetch.uri(uri)
 
@@ -127,7 +138,7 @@ Possible formats for `uri`:
 
 A public key object.
 
-## keys.fetch.hkp(fingerprint, [keyserverBaseUrl])
+### keys.fetch.hkp(fingerprint, [keyserverBaseUrl])
 
 _(async)_ keys.fetch.hkp(fingerprint, [keyserverBaseUrl])
 
@@ -146,7 +157,7 @@ Fetches a key using HKP-compatible key servers.
 
 A public key object.
 
-## keys.fetch.hkp(email, [keyserverBaseUrl])
+### keys.fetch.hkp(email, [keyserverBaseUrl])
 
 _(async)_ keys.fetch.hkp(email, [keyserverBaseUrl])
 
@@ -165,7 +176,7 @@ Fetches a key using HKP-compatible key servers.
 
 A public key object.
 
-## keys.fetch.wkd(wkdId)
+### keys.fetch.wkd(wkdId)
 
 _(async)_ keys.fetch.wkd(wkdId)
 
@@ -183,7 +194,7 @@ Fetches a key using the WKD protocol.
 
 A public key object.
 
-## keys.fetch.plaintext(keyPlaintext)
+### keys.fetch.plaintext(keyPlaintext)
 
 _(async)_ keys.fetch.plaintext(keyPlaintext)
 
@@ -199,7 +210,7 @@ Parses the `keyPlaintext`.
 
 A public key object.
 
-## signatures.verify(uri, [fingerprint], [opts])
+### signatures.verify(uri, [fingerprint], [opts])
 
 _(async)_ doip.signatures.verify(signature, [opts])
 

docs/doipjs/old.md

@@ -0,0 +1,257 @@
+# Claim (class)
+
+## Constructor
+
+new Claim([uri], [fingerprint])
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                      |
+| ----------- | ------ | --------- | -------------------------------- |
+| uri         | string | false     | the URI to an identity to verify |
+| fingerprint | string | false     | the fingerprint of the claim     |
+
+## Properties
+
+### state
+
+The current state of the Claim object.
+
+**Values:**
+
+| Name     | Description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| init     | The claim has just been initialized                               |
+| matched  | The claim has been matched to candidate claim definitions         |
+| verified | The claim has attempted to verify all candidate claim definitions |
+
+### matches
+
+Returns the matches
+
+## Methods
+
+### match()
+
+Verifies the identity behind the provided **uri** using the **fingerprint**.
+
+**Parameters**
+
+| 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               | 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', 'fallback', 'always', 'never']        |
+| doipProxyHostname  | string  | 'proxy.keyoxide.org' | the hostname of the proxy server                                       |
+| twitterBearerToken | string  | ''                   | the Twitter API bearer token used for Twitter verification             |
+| nitterInstance     | string  | ''                   | the domain name of the nitter instance to use for Twitter verification |
+
+When the `proxyPolicy` option is to `adaptive`, the chosen strategy is
+the one suggested by the service provider.
+
+By default, Twitter accounts are not verified. Either provide a
+[Twitter bearer token](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens)
+(as `twitterBearerToken`) or the domain name of a Nitter instance (as
+`nitterInstance`) to enable Twitter account verification. If both values are
+provided, only the Twitter bearer token is used.
+
+Note that Nitter instances are subject to rate limiting which would instantly
+break Twitter account verification.
+
+**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`.
+
+### claims.verify(uriArray, [fingerprint], [opts])
+
+_(async)_ doip.claims.verify(array, [fingerprint], [opts])
+
+Verifies the identity behind the provided **array of uris** using the **fingerprint**.
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                  |
+| ----------- | ------ | --------- | ---------------------------- |
+| uriArray    | array  | true      | array of uris                |
+| fingerprint | string | false     | the fingerprint of the claim |
+| opts        | object | false     | options (see below)          |
+
+**Options**
+
+See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
+
+**Returns**
+
+An array of objects with claim verification results (see
+[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)).
+
+### claims.verify(key, [fingerprint], [opts])
+
+_(async)_ doip.claims.verify(key, [fingerprint], [opts])
+
+Verifies the identity behind the claims contained within the provided
+**key** using the **fingerprint**. This key is outputted by the
+[keys.fetch.\*()](#keysfetchuriuri) commands.
+
+**Parameters**
+
+| Name        | Type   | Mandatory | Description                  |
+| ----------- | ------ | --------- | ---------------------------- |
+| key         | object | true      | a public key                 |
+| fingerprint | string | false     | the fingerprint of the claim |
+| opts        | object | false     | options (see below)          |
+
+**Options**
+
+See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
+
+**Returns**
+
+An array of objects with claim verification results (see
+[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)).
+
+### keys.fetch.uri(uri)
+
+_(async)_ keys.fetch.uri(uri)
+
+Fetches a key based on the provided `uri`. This simply serves as a shortcut to
+other `keys.fetch.*` commands.
+
+**Parameters**
+
+| Name | Type   | Mandatory | Description           |
+| ---- | ------ | --------- | --------------------- |
+| uri  | string | true      | public key identifier |
+
+Possible formats for `uri`:
+
+`hkp:FINGERPRINT` ⇒ `keys.fetch.hkp(FINGERPRINT)`  
+`hkp:FINGERPRINT:KEYSERVER` ⇒ `keys.fetch.hkp(FINGERPRINT, KEYSERVER)`  
+`hkp:EMAIL` ⇒ `keys.fetch.hkp(EMAIL)`  
+`hkp:EMAIL:KEYSERVER` ⇒ `keys.fetch.hkp(EMAIL, KEYSERVER)`  
+`wkd:EMAIL` ⇒ `keys.fetch.wkd(EMAIL)`  
+`kb:USERNAME:FINGERPRINT` ⇒ `keys.fetch.keybase(USERNAME, FINGERPRINT)`
+
+**Returns**
+
+A public key object.
+
+### keys.fetch.hkp(fingerprint, [keyserverBaseUrl])
+
+_(async)_ keys.fetch.hkp(fingerprint, [keyserverBaseUrl])
+
+Fetches a key using HKP-compatible key servers.
+
+**Parameters**
+
+| Name             | Type   | Mandatory | Description           |
+| ---------------- | ------ | --------- | --------------------- |
+| fingerprint      | string | true      | public key identifier |
+| keyserverBaseUrl | string | false     | base URL of keyserver |
+
+`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`.
+
+**Returns**
+
+A public key object.
+
+### keys.fetch.hkp(email, [keyserverBaseUrl])
+
+_(async)_ keys.fetch.hkp(email, [keyserverBaseUrl])
+
+Fetches a key using HKP-compatible key servers.
+
+**Parameters**
+
+| Name             | Type   | Mandatory | Description           |
+| ---------------- | ------ | --------- | --------------------- |
+| email            | string | true      | public key identifier |
+| keyserverBaseUrl | string | false     | base URL of keyserver |
+
+`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`.
+
+**Returns**
+
+A public key object.
+
+### keys.fetch.wkd(wkdId)
+
+_(async)_ keys.fetch.wkd(wkdId)
+
+Fetches a key using the WKD protocol.
+
+**Parameters**
+
+| Name  | Type   | Mandatory | Description    |
+| ----- | ------ | --------- | -------------- |
+| wkdId | string | true      | WKD identifier |
+
+`wkdId` looks like an email address and is formatted as `username@domain.org`.
+
+**Returns**
+
+A public key object.
+
+### keys.fetch.plaintext(keyPlaintext)
+
+_(async)_ keys.fetch.plaintext(keyPlaintext)
+
+Parses the `keyPlaintext`.
+
+**Parameters**
+
+| Name         | Type   | Mandatory | Description       |
+| ------------ | ------ | --------- | ----------------- |
+| keyPlaintext | string | true      | ASCII key content |
+
+**Returns**
+
+A public key object.
+
+### signatures.verify(uri, [fingerprint], [opts])
+
+_(async)_ doip.signatures.verify(signature, [opts])
+
+Verifies the identity behind the claims in the provided clear-signed **signature**.
+
+**Parameters**
+
+| Name      | Type   | Mandatory | Description               |
+| --------- | ------ | --------- | ------------------------- |
+| signature | string | true      | the clear-sgned signature |
+| opts      | object | false     | options (see below)       |
+
+**Options**
+
+See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts).
+
+**Returns**
+
+```json
+{
+  "errors": [ ... ],
+  "publicKey": { ... },
+  "fingerprint": "...",
+  "serviceproviderData": { ... }
+}
+```

docs/installation.md

@@ -15,7 +15,7 @@ npm install --save doipjs
 Install on website by including the following HTML snippet:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/doipjs@0.11.2/dist/doip.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/doipjs@0.12.0/dist/doip.min.js"></script>
 ```
 
 Next step: [quick start (Node.js)](quickstart-nodejs.md) and [quick start (browser)](quickstart-browser.md)

docs/quickstart-browser.md

@@ -4,7 +4,10 @@ Basic example:
 
 ```javascript
 const verifyIdentity = async (url, fp) => {
-  console.log(await doip.claims.verify(url, fp))
+  const claim = new doip.Claim(url, fp)
+  claim.match()
+  await claim.verify()
+  console.log(claim.result)
 }
 verifyIdentity('dns:doip.rocks', '9f0048ac0b23301e1f77e994909f6bd6f80f485d')
 ```

docs/quickstart-nodejs.md

@@ -6,7 +6,10 @@ Basic example:
 const doip = require('doip')
 
 const verifyIdentity = async (url, fp) => {
-  console.log(await doip.claims.verify(url, fp))
+  const claim = new doip.Claim(url, fp)
+  claim.match()
+  await claim.verify()
+  console.log(claim.result)
 }
 verifyIdentity('dns:doip.rocks', '9f0048ac0b23301e1f77e994909f6bd6f80f485d')
 ```