# API

## claims.verify(uri, [fingerprint], [opts])

_(async)_ doip.claims.verify(uri, [fingerprint], [opts])

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": { ... }
}
```