From 3ef328ea441ab243bd1489d5b68ae175b23e86bc Mon Sep 17 00:00:00 2001 From: Yarmo Mackenbach Date: Mon, 19 Apr 2021 14:35:06 +0200 Subject: [PATCH] WIP Update docs --- docs/_coverpage.md | 2 +- docs/_sidebar.md | 10 +- docs/doipjs/class_claim.md | 129 +++++++++++++ docs/{api.md => doipjs/module_keys.md} | 33 ++-- docs/doipjs/old.md | 257 +++++++++++++++++++++++++ docs/installation.md | 2 +- docs/quickstart-browser.md | 5 +- docs/quickstart-nodejs.md | 5 +- 8 files changed, 423 insertions(+), 20 deletions(-) create mode 100644 docs/doipjs/class_claim.md rename docs/{api.md => doipjs/module_keys.md} (90%) create mode 100644 docs/doipjs/old.md diff --git a/docs/_coverpage.md b/docs/_coverpage.md index 01e15f1..d06b626 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -1,4 +1,4 @@ -# doip.js 0.11.2 +# doip.js 0.12.0 diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 68c3794..c70fb45 100644 --- a/docs/_sidebar.md +++ b/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) diff --git a/docs/doipjs/class_claim.md b/docs/doipjs/class_claim.md new file mode 100644 index 0000000..a980767 --- /dev/null +++ b/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}` + +## 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)). diff --git a/docs/api.md b/docs/doipjs/module_keys.md similarity index 90% rename from docs/api.md rename to docs/doipjs/module_keys.md index 1bf3361..e521000 100644 --- a/docs/api.md +++ b/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]) diff --git a/docs/doipjs/old.md b/docs/doipjs/old.md new file mode 100644 index 0000000..d3bb3ff --- /dev/null +++ b/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": { ... } +} +``` diff --git a/docs/installation.md b/docs/installation.md index b136ee9..b3a93b8 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,7 +15,7 @@ npm install --save doipjs Install on website by including the following HTML snippet: ```html - + ``` Next step: [quick start (Node.js)](quickstart-nodejs.md) and [quick start (browser)](quickstart-browser.md) diff --git a/docs/quickstart-browser.md b/docs/quickstart-browser.md index ba1d90f..d94423a 100644 --- a/docs/quickstart-browser.md +++ b/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') ``` diff --git a/docs/quickstart-nodejs.md b/docs/quickstart-nodejs.md index da007d4..00b993f 100644 --- a/docs/quickstart-nodejs.md +++ b/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') ```