doipjs/docs/api.md

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 (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 object.

{
  "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, ...).

Returns

An array of objects with claim verification results (see claims.verify(uri, ...)).

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.*() 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, ...).

Returns

An array of objects with claim verification results (see claims.verify(uri, ...)).

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, ...).

Returns

{
  "errors": [ ... ],
  "publicKey": { ... },
  "fingerprint": "...",
  "serviceproviderData": { ... }
}