myriation/doipjs
1
0
Fork 0
forked from Mirrors/doipjs
Code Pull requests Packages 1 Activity

fix: fix jsdoc errors found by eslint

Browse source
This commit is contained in:
Yarmo Mackenbach 2024-01-27 18:00:55 +01:00
parent 3f8579513a
commit 336029fd87
50 changed files with 514 additions and 430 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
src/asp.js
View file

@ -33,9 +33,9 @@ const SupportedCryptoAlg = ['EdDSA', 'ES256', 'ES256K', 'ES384', 'ES512']
* Fetch a public key using Web Key Directory
* @function
* @param {string} uri - ASPE URI
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The fetched profile
* @example
* const key = doip.aspe.fetchASPE('aspe:domain.tld:1234567890');
* const key = await doip.aspe.fetchASPE('aspe:domain.example:1234567890');
*/
export async function fetchASPE (uri) {
const re = /aspe:(.*):(.*)/
@ -77,13 +77,13 @@ export async function fetchASPE (uri) {
}
/**
* Fetch a public key using Web Key Directory
* Parse a JWS and extract the profile it contains
* @function
* @param {string} profileJws - Compact-Serialized profile JWS
* @param {string} uri - The ASPE URI associated with the profile
* @returns {Promise<Profile>}
* @param {string} uri - The ASPE URI associated with the profile
* @returns {Promise<Profile>} The extracted profile
* @example
* const key = doip.aspe.parseProfileJws('...');
* const key = await doip.aspe.parseProfileJws('...');
*/
export async function parseProfileJws (profileJws, uri) {
const matches = uri.match(/aspe:(.*):(.*)/)
@ -172,8 +172,8 @@ export async function parseProfileJws (profileJws, uri) {
/**
* Compute the fingerprint for JWK keys
* @function
* @param {joseMod.JWK} key
* @returns {Promise<string>}
* @param {joseMod.JWK} key - The JWK public key for which to compute the fingerprint
* @returns {Promise<string>} The computed fingerprint
*/
export async function computeJwkFingerprint (key) {
const thumbprint = await calculateJwkThumbprint(key, 'sha512')

31
src/claim.js
View file

@ -18,11 +18,11 @@ import { isUri } from 'valid-url'
import mergeOptions from 'merge-options'
import { fetch } from './proofs.js'
import { run } from './verifications.js'
import * as verificationsMod from './verifications.js'
import { list, data as _data } from './serviceProviders/index.js'
import { opts as _opts } from './defaults.js'
import { ClaimStatus } from './enums.js'
import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/**
* @class
@ -31,17 +31,16 @@ import { ServiceProvider } from './serviceProvider.js'
* @property {string} fingerprint - The fingerprint to verify the claim against
* @property {number} status - The current status code of the claim
* @property {Array<object>} matches - The claim definitions matched against the URI
* @example
* const claim = doip.Claim();
* const claim = doip.Claim('dns:domain.tld?type=TXT');
* const claim = doip.Claim('dns:domain.tld?type=TXT', '123abc123abc');
*/
export class Claim {
/**
* Initialize a Claim object
* @constructor
* @param {string} [uri] - The URI of the identity claim
* @param {string} [fingerprint] - The fingerprint of the OpenPGP key
* @example
* const claim = doip.Claim();
* const claim = doip.Claim('dns:domain.tld?type=TXT');
* const claim = doip.Claim('dns:domain.tld?type=TXT', '123abc123abc');
*/
constructor (uri, fingerprint) {
// Verify validity of URI
@ -79,8 +78,8 @@ export class Claim {
/**
* @function
* @param {object} claimObject
* @returns {Claim | Error}
* @param {object} claimObject - JSON representation of a claim
* @returns {Claim | Error} Parsed claim
* @example
* doip.Claim.fromJSON(JSON.stringify(claim));
*/
@ -218,7 +217,7 @@ export class Claim {
* regardless of the result.
* @async
* @function
* @param {object} [opts] - Options for proxy, fetchers
* @param {Types.VerificationConfig} [opts] - Options for proxy, fetchers
*/
async verify (opts) {
if (this._status === ClaimStatus.INIT) {
@ -246,7 +245,7 @@ export class Claim {
let claimData = this._matches[index]
/** @type {verificationsMod.VerificationResult} */
/** @type {Types.VerificationResult} */
let verificationResult = null
let proofData = null
let proofFetchError
@ -312,7 +311,7 @@ export class Claim {
* of the candidates is unambiguous. An ambiguous claim should never be
* displayed in an user interface when its result is negative.
* @function
* @returns {boolean}
* @returns {boolean} Whether the claim is ambiguous
*/
isAmbiguous () {
if (this._status < ClaimStatus.MATCHED) {
@ -329,7 +328,7 @@ export class Claim {
* Get a JSON representation of the Claim object. Useful when transferring
* data between instances/machines.
* @function
* @returns {object}
* @returns {object} JSON reprentation of the claim
*/
toJSON () {
let displayProfileName = this._uri
@ -364,8 +363,8 @@ export class Claim {
}
/**
* @param {object} claimObject
* @returns {Claim | Error}
* @param {object} claimObject - JSON representation of a claim
* @returns {Claim | Error} Parsed claim
*/
function importJsonClaimVersion1 (claimObject) {
if (!('claimVersion' in claimObject && claimObject.claimVersion === 1)) {
@ -405,8 +404,8 @@ function importJsonClaimVersion1 (claimObject) {
}
/**
* @param {object} claimObject
* @returns {Claim | Error}
* @param {object} claimObject - JSON representation of a claim
* @returns {Claim | Error} Parsed claim
*/
function importJsonClaimVersion2 (claimObject) {
if (!('claimVersion' in claimObject && claimObject.claimVersion === 2)) {

24
src/defaults.js
View file

@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.
*/
import { ProxyPolicy } from './enums.js'
import * as Types from './types.js'
/**
* Contains default values
@ -21,26 +22,9 @@ import { ProxyPolicy } from './enums.js'
*/
/**
* The default options used throughout the library
* @constant {object}
* @property {object} proxy - Options related to the proxy
* @property {string|null} proxy.hostname - The hostname of the proxy
* @property {string} proxy.policy - The policy that defines when to use a proxy ({@link module:enums~ProxyPolicy|here})
* @property {object} claims - Options related to claim verification
* @property {object} claims.activitypub - Options related to the verification of activitypub claims
* @property {string|null} claims.activitypub.url - The URL of the verifier account
* @property {string|null} claims.activitypub.privateKey - The private key to sign the request
* @property {object} claims.irc - Options related to the verification of IRC claims
* @property {string|null} claims.irc.nick - The nick that the library uses to connect to the IRC server
* @property {object} claims.matrix - Options related to the verification of Matrix claims
* @property {string|null} claims.matrix.instance - The server hostname on which the library can log in
* @property {string|null} claims.matrix.accessToken - The access token required to identify the library ({@link https://www.matrix.org/docs/guides/client-server-api|Matrix docs})
* @property {object} claims.telegram - Options related to the verification of Telegram claims
* @property {string|null} claims.telegram.token - The Telegram API's token ({@link https://core.telegram.org/bots/api#authorizing-your-bot|Telegram docs})
* @property {object} claims.xmpp - Options related to the verification of XMPP claims
* @property {string|null} claims.xmpp.service - The server hostname on which the library can log in
* @property {string|null} claims.xmpp.username - The username used to log in
* @property {string|null} claims.xmpp.password - The password used to log in
* The default claim verification config used throughout the library
* @constant
* @type {Types.VerificationConfig}
*/
export const opts = {
proxy: {

2
src/enums.js
View file

@ -115,7 +115,7 @@ export const ClaimFormat = {
}
/**
* How to find the claim inside the proof's JSON data
* How to find the proof inside the fetched data
* @readonly
* @enum {string}
*/

20
src/fetcher/activitypub.js
View file

@ -18,22 +18,24 @@ import isURL from 'validator/lib/isURL.js'
import { isNode } from 'browser-or-node'
import crypto from 'crypto'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.url - The URL of the account to verify
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request
* @param {object} opts.claims
* @param {object} opts.claims.activitypub
* @param {string} opts.claims.activitypub.url - The URL of the verifier account
* @param {string} opts.claims.activitypub.privateKey - The private key to sign the request
* @returns {Promise<object>}
* @param {object} data - Data used in the request
* @param {string} data.url - The URL of the account to verify
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched ActivityPub object
*/
export async function fn (data, opts) {
let timeoutHandle

15
src/fetcher/aspe.js
View file

@ -17,7 +17,13 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js'
import { version } from '../constants.js'
import { parseProfileJws } from '../asp.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
@ -26,10 +32,11 @@ const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.aspeUri - ASPE URI of the targeted profile
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
* @param {object} data - Data used in the request
* @param {string} data.aspeUri - ASPE URI of the targeted profile
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched claims from an ASP profile
*/
export async function fn (data, opts) {
let timeoutHandle

15
src/fetcher/dns.js
View file

@ -15,17 +15,24 @@ limitations under the License.
*/
import { isBrowser } from 'browser-or-node'
import dns from 'dns'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.domain - The targeted domain
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object>}
* @param {object} data - Data used in the request
* @param {string} data.domain - The targeted domain
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched DNS records
*/
export async function fn (data, opts) {
if (isBrowser) {

17
src/fetcher/graphql.js
View file

@ -15,18 +15,25 @@ limitations under the License.
*/
import axios from 'axios'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a GraphQL query via HTTP request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at the GraphQL HTTP endpoint
* @param {string} data.query - The GraphQL query to fetch the data containing the proof
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at the GraphQL HTTP endpoint
* @param {string} data.query - The GraphQL query to fetch the data containing the proof
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched GraphQL object
*/
export async function fn (data, opts) {
let timeoutHandle

17
src/fetcher/http.js
View file

@ -16,18 +16,25 @@ limitations under the License.
import axios from 'axios'
import { ProofFormat } from '../enums.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at targeted content
* @param {string} data.format - The format of the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at targeted content
* @param {string} data.format - The format of the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object|string>} The fetched JSON object or text
*/
export async function fn (data, opts) {
let timeoutHandle

19
src/fetcher/irc.js
View file

@ -15,22 +15,25 @@ limitations under the License.
*/
import irc from 'irc-upd'
import isAscii from 'validator/lib/isAscii.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 20000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.nick - The nick of the targeted account
* @param {string} data.domain - The domain on which the targeted account is registered
* @param {object} data - Data used in the request
* @param {string} data.nick - The nick of the targeted account
* @param {string} data.domain - The domain on which the targeted account is registered
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request
* @param {object} opts.claims
* @param {object} opts.claims.irc
* @param {string} opts.claims.irc.nick - The nick to be used by the library to log in
* @returns {Promise<object>}
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<string[]>} The fetched proofs from an IRC account
*/
export async function fn (data, opts) {
let timeoutHandle

22
src/fetcher/matrix.js
View file

@ -17,23 +17,25 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.eventId - The identifier of the targeted post
* @param {string} data.roomId - The identifier of the room containing the targeted post
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request
* @param {object} opts.claims
* @param {object} opts.claims.matrix
* @param {string} opts.claims.matrix.instance - The server hostname on which the library can log in
* @param {string} opts.claims.matrix.accessToken - The access token required to identify the library ({@link https://www.matrix.org/docs/guides/client-server-api|Matrix docs})
* @returns {Promise<object>}
* @param {object} data - Data used in the request
* @param {string} data.eventId - The identifier of the targeted post
* @param {string} data.roomId - The identifier of the room containing the targeted post
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched Matrix object
*/
export async function fn (data, opts) {
let timeoutHandle

17
src/fetcher/openpgp.js
View file

@ -18,18 +18,25 @@ import { readKey } from 'openpgp'
import { OpenPgpQueryProtocol } from '../enums.js'
import { version } from '../constants.js'
import { parsePublicKey } from '../openpgp.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at targeted content
* @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
* @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at targeted content
* @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched notations from an OpenPGP key
*/
export async function fn (data, opts) {
let timeoutHandle

21
src/fetcher/telegram.js
View file

@ -16,22 +16,25 @@ limitations under the License.
import axios from 'axios'
import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
/**
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.chat - Telegram public chat username
* @param {string} data.user - Telegram user username
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request
* @param {object} opts.claims
* @param {object} opts.claims.telegram
* @param {string} opts.claims.telegram.token - The Telegram Bot API token
* @returns {Promise<object|string>}
* @param {object} data - Data used in the request
* @param {string} data.chat - Telegram public chat username
* @param {string} data.user - Telegram user username
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object|string>} The fetched Telegram object
*/
export async function fn (data, opts) {
let timeoutHandle

42
src/fetcher/xmpp.js
View file

@ -17,18 +17,31 @@ import { client, xml } from '@xmpp/client'
import debug from '@xmpp/debug'
import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.js'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000
let xmpp = null
let iqCaller = null
const xmppStart = async (service, username, password) => {
/**
* Start the XMPP client
* @function
* @async
* @param {Types.XmppClaimVerificationConfig} params - XMPP claim verification config
* @returns {Promise<object>} The fetched proofs from an XMPP account
*/
const xmppStart = async (params) => {
return new Promise((resolve, reject) => {
const xmpp = client({
service,
username,
password
service: params.service,
username: params.username,
password: params.password
})
if (process.env.NODE_ENV !== 'production') {
debug(xmpp, true)
@ -48,16 +61,11 @@ const xmppStart = async (service, username, password) => {
* Execute a fetch request
* @function
* @async
* @param {object} data - Data used in the request
* @param {string} data.id - The identifier of the targeted account
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request
* @param {object} opts.claims
* @param {object} opts.claims.xmpp
* @param {string} opts.claims.xmpp.service - The server hostname on which the library can log in
* @param {string} opts.claims.xmpp.username - The username used to log in
* @param {string} opts.claims.xmpp.password - The password used to log in
* @returns {Promise<object>}
* @param {object} data - Data used in the request
* @param {string} data.id - The identifier of the targeted account
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<Array<string>>} The fetched proofs from an XMPP account
*/
export async function fn (data, opts) {
try {
@ -69,11 +77,7 @@ export async function fn (data, opts) {
}
if (!xmpp || xmpp.status !== 'online') {
const xmppStartRes = await xmppStart(
opts.claims.xmpp.service,
opts.claims.xmpp.username,
opts.claims.xmpp.password
)
const xmppStartRes = await xmppStart(opts.claims.xmpp)
xmpp = xmppStartRes.xmpp
iqCaller = xmppStartRes.iqCaller
}

1
src/index.js
View file

@ -28,3 +28,4 @@ export * as utils from './utils.js'
export * as verifications from './verifications.js'
export * as schemas from './schemas.js'
export * as fetcher from './fetcher/index.js'
export * as types from './types.js'

31
src/openpgp.js
View file

@ -31,17 +31,16 @@ import { Persona } from './persona.js'
/**
* Fetch a public key using keyservers
* @function
* @param {string} identifier - Fingerprint or email address
* @param {string} [keyserverDomain=keys.openpgp.org] - Domain of the keyserver
* @returns {Promise<Profile>}
* @param {string} identifier - Fingerprint or email address
* @param {string} [keyserverDomain] - Domain of the keyserver
* @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example
* const key1 = doip.keys.fetchHKP('alice@domain.tld');
* const key2 = doip.keys.fetchHKP('123abc123abc');
* const key3 = doip.keys.fetchHKP('123abc123abc', 'pgpkeys.eu');
*/
export async function fetchHKP (identifier, keyserverDomain) {
const keyserverBaseUrl = keyserverDomain
? `https://${keyserverDomain}`
: 'https://keys.openpgp.org'
export async function fetchHKP (identifier, keyserverDomain = 'keys.openpgp.org') {
const keyserverBaseUrl = `https://${keyserverDomain ?? 'keys.openpgp.org'}`
const hkp = new HKP(keyserverBaseUrl)
const lookupOpts = {
@ -76,7 +75,7 @@ export async function fetchHKP (identifier, keyserverDomain) {
* Fetch a public key using Web Key Directory
* @function
* @param {string} identifier - Identifier of format 'username@domain.tld`
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example
* const key = doip.keys.fetchWKD('alice@domain.tld');
*/
@ -113,9 +112,9 @@ export async function fetchWKD (identifier) {
/**
* Fetch a public key from Keybase
* @function
* @param {string} username - Keybase username
* @param {string} fingerprint - Fingerprint of key
* @returns {Promise<Profile>}
* @param {string} username - Keybase username
* @param {string} fingerprint - Fingerprint of key
* @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example
* const key = doip.keys.fetchKeybase('alice', '123abc123abc');
*/
@ -155,10 +154,10 @@ export async function fetchKeybase (username, fingerprint) {
}
/**
* Get a public key from plaintext data
* Get a public key from armored public key text data
* @function
* @param {string} rawKeyContent - Plaintext ASCII-formatted public key data
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile from the armored public key
* @example
* const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
*
@ -185,7 +184,7 @@ export async function fetchPlaintext (rawKeyContent) {
* Fetch a public key using an URI
* @function
* @param {string} uri - URI that defines the location of the key
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example
* const key1 = doip.keys.fetchURI('hkp:alice@domain.tld');
* const key2 = doip.keys.fetchURI('hkp:123abc123abc');
@ -231,7 +230,7 @@ export async function fetchURI (uri) {
* This function will also try and parse the input as a plaintext key
* @function
* @param {string} identifier - URI that defines the location of the key
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example
* const key1 = doip.keys.fetch('alice@domain.tld');
* const key2 = doip.keys.fetch('123abc123abc');
@ -273,7 +272,7 @@ export async function fetch (identifier) {
* Process a public key to get a profile
* @function
* @param {PublicKey} publicKey - The public key to parse
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile from the processed OpenPGP key
* @example
* const key = doip.keys.fetchURI('hkp:alice@domain.tld');
* const profile = doip.keys.parsePublicKey(key);

38
src/persona.js
View file

@ -16,9 +16,8 @@ limitations under the License.
import { Claim } from './claim.js'
/**
* A persona with identity claims
* @class
* @constructor
* @classdesc A persona with identity claims
* @public
* @example
* const claim = Claim('https://alice.tld', '123');
@ -26,8 +25,8 @@ import { Claim } from './claim.js'
*/
export class Persona {
/**
* @param {string} name
* @param {Claim[]} claims
* @param {string} name - Name of the persona
* @param {Claim[]} claims - Claims of the persona
*/
constructor (name, claims) {
/**
@ -81,10 +80,11 @@ export class Persona {
}
/**
* Parse a JSON object and convert it into a persona
* @function
* @param {object} personaObject
* @param {number} profileVersion
* @returns {Persona | Error}
* @param {object} personaObject - JSON representation of a persona
* @param {number} profileVersion - Version of the Profile containing the persona
* @returns {Persona | Error} Parsed persona
* @example
* doip.Persona.fromJSON(JSON.stringify(persona), 2);
*/
@ -112,46 +112,52 @@ export class Persona {
}
/**
* Set the persona's identifier
* @function
* @param {string} identifier
* @param {string} identifier - Identifier of the persona
*/
setIdentifier (identifier) {
this.identifier = identifier
}
/**
* Set the persona's description
* @function
* @param {string} description
* @param {string} description - Description of the persona
*/
setDescription (description) {
this.description = description
}
/**
* Set the persona's email address
* @function
* @param {string} email
* @param {string} email - Email address of the persona
*/
setEmailAddress (email) {
this.email = email
}
/**
* Set the URL to the persona's avatar
* @function
* @param {string} avatarUrl
* @param {string} avatarUrl - URL to the persona's avatar
*/
setAvatarUrl (avatarUrl) {
this.avatarUrl = avatarUrl
}
/**
* Add a claim
* @function
* @param {Claim} claim
* @param {Claim} claim - Claim to add
*/
addClaim (claim) {
this.claims.push(claim)
}
/**
* Revoke the persona
* @function
*/
revoke () {
@ -159,9 +165,9 @@ export class Persona {
}
/**
* Get a JSON representation of the Profile object
* Get a JSON representation of the persona
* @function
* @returns {object}
* @returns {object} JSON representation of the persona
*/
toJSON () {
return {
@ -178,8 +184,8 @@ export class Persona {
}
/**
* @param {object} personaObject
* @returns {Persona | Error}
* @param {object} personaObject - JSON representation of a persona
* @returns {Persona | Error} Parsed persona
*/
function importJsonPersonaVersion2 (personaObject) {
const claims = personaObject.claims.map(x => Claim.fromJSON(x))

94
src/profile.js
View file

@ -13,22 +13,14 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
import { PublicKey } from 'openpgp'
import * as joseMod from 'jose'
import { PublicKeyFetchMethod, PublicKeyEncoding, PublicKeyType, ProfileType } from './enums.js'
import { Persona } from './persona.js'
import * as Types from './types.js'
/**
* The online verifier instance of identity profiles like Keyoxide's web interface
* @typedef {Object} ProfileVerifier
* @property {string} name - Name of the profile verifier
* @property {string} url - URL to the profile verifier
*/
/**
* A profile of personas with identity claims
* @function
* @param {Array<Persona>} personas
* @class [Types.Profile]
* @classdesc A profile of personas with identity claims
* @param {Array<Persona>} personas - Personas of the profile
* @public
* @example
* const claim = Claim('https://alice.tld', '123');
@ -39,17 +31,12 @@ export class Profile {
/**
* Create a new profile
* @function
* @param {ProfileType} profileType
* @param {string} identifier
* @param {Array<Persona>} personas
* @param {ProfileType} profileType - Type of profile (ASP, OpenPGP, etc.)
* @param {string} identifier - Profile identifier (fingerprint, URI, etc.)
* @param {Array<Persona>} personas - Personas of the profile
* @public
*/
constructor (profileType, identifier, personas) {
/**
* Profile version
* @type {number}
* @public
*/
this.profileVersion = 2
/**
* Profile version
@ -77,78 +64,34 @@ export class Profile {
this.primaryPersonaIndex = personas.length > 0 ? 0 : -1
/**
* The cryptographic key associated with the profile
* @property {object}
* @type {Types.ProfilePublicKey}
* @public
*/
this.publicKey = {
/**
* The type of cryptographic key
* @type {PublicKeyType}
* @public
*/
keyType: PublicKeyType.NONE,
/**
* The fingerprint of the cryptographic key
* @type {string | null}
* @public
*/
fingerprint: null,
/**
* The encoding of the cryptographic key
* @type {PublicKeyEncoding}
* @public
*/
encoding: PublicKeyEncoding.NONE,
/**
* The encoded cryptographic key
* @type {string | null}
* @public
*/
encodedKey: null,
/**
* The raw cryptographic key as object (to be removed during toJSON())
* @type {PublicKey | joseMod.JWK | null}
* @public
*/
key: null,
/**
* Details on how to fetch the public key
* @property {object}
* @public
*/
fetch: {
/**
* The method to fetch the key
* @type {PublicKeyFetchMethod}
* @public
*/
method: PublicKeyFetchMethod.NONE,
/**
* The query to fetch the key
* @type {string | null}
* @public
*/
query: null,
/**
* The URL the method eventually resolved to
* @type {string | null}
* @public
*/
resolvedUrl: null
}
}
/**
* List of verifier URLs
* @type {ProfileVerifier[]}
* @type {Types.ProfileVerifier[]}
* @public
*/
this.verifiers = []
}
/**
* Parse a JSON object and convert it into a profile
* @function
* @param {object} profileObject
* @returns {Profile | Error}
* @param {object} profileObject - JSON representation of a profile
* @returns {Profile | Error} Parsed profile
* @example
* doip.Profile.fromJSON(JSON.stringify(profile));
*/
@ -176,18 +119,19 @@ export class Profile {
}
/**
* Add profile verifier to the profile
* @function
* @param {string} name
* @param {string} url
* @param {string} name - Name of the verifier
* @param {string} url - URL of the verifier
*/
addVerifier (name, url) {
this.verifiers.push({ name, url })
}
/**
* Get a JSON representation of the Profile object
* Get a JSON representation of the profile
* @function
* @returns {object}
* @returns {object} JSON representation of the profile
*/
toJSON () {
return {
@ -213,8 +157,8 @@ export class Profile {
}
/**
* @param {object} profileObject
* @returns {Profile | Error}
* @param {object} profileObject - JSON representation of the profile
* @returns {Profile | Error} Parsed profile
*/
function importJsonProfileVersion2 (profileObject) {
if (!('profileVersion' in profileObject && profileObject.profileVersion === 2)) {

15
src/proofs.js
View file

@ -18,6 +18,7 @@ import { fetcher } from './index.js'
import { generateProxyURL } from './utils.js'
import { ProxyPolicy, ProofAccessRestriction } from './enums.js'
import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/**
* @module proofs
@ -31,8 +32,8 @@ import { ServiceProvider } from './serviceProvider.js'
* approach is possible.
* @async
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @param {Types.VerificationConfig} opts - Options to enable the request
* @returns {Promise<object|string>} Fetched proof data
*/
export async function fetch (data, opts) {
if (isNode) {
@ -45,7 +46,7 @@ export async function fetch (data, opts) {
/**
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @returns {Promise<object|string>} Fetched proof data
*/
const handleBrowserRequests = (data, opts) => {
switch (opts.proxy.policy) {
@ -88,7 +89,7 @@ const handleBrowserRequests = (data, opts) => {
/**
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @returns {Promise<object|string>} Fetched proof data
*/
const handleNodeRequests = (data, opts) => {
switch (opts.proxy.policy) {
@ -109,7 +110,7 @@ const handleNodeRequests = (data, opts) => {
/**
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @returns {Promise<object|string>} Fetched proof data
*/
const createDefaultRequestPromise = (data, opts) => {
return new Promise((resolve, reject) => {
@ -135,7 +136,7 @@ const createDefaultRequestPromise = (data, opts) => {
/**
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @returns {Promise<object|string>} Fetched proof data
*/
const createProxyRequestPromise = (data, opts) => {
return new Promise((resolve, reject) => {
@ -174,7 +175,7 @@ const createProxyRequestPromise = (data, opts) => {
/**
* @param {ServiceProvider} data - Data from a claim definition
* @param {object} opts - Options to enable the request
* @returns {Promise<object|string>}
* @returns {Promise<object|string>} Fetched proof data
*/
const createFallbackRequestPromise = (data, opts) => {
return new Promise((resolve, reject) => {

126
src/serviceProvider.js
View file

@ -13,140 +13,44 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestriction, ProofFormat } from "./enums"
/**
* The method to find the proof inside the response data
* @typedef {Object} ProofTarget
* @property {ClaimFormat} format - How the response data is formatted
* @property {EntityEncodingFormat} encoding - How the response data is encoded
* @property {ClaimRelation} relation - How the proof is related to the response data
* @property {string[]} path - Path to the proof inside the response data object
*/
import * as Types from './types.js'
/**
* A service provider matched to an identity claim
* @class
* @constructor
* @public
*/
export class ServiceProvider {
/**
* @param {object} spObj
* @param {Types.ServiceProviderObject} serviceProviderObject - JSON representation of a {@link ServiceProvider}
*/
constructor (spObj) {
constructor (serviceProviderObject) {
/**
* Details about the service provider
* @property {object}
* @type {Types.ServiceProviderAbout}
*/
this.about = {
/**
* Identifier of the service provider (no whitespace or symbols, lowercase)
* @type {string}
*/
id: spObj.about.id,
/**
* Full name of the service provider
* @type {string}
*/
name: spObj.about.name,
/**
* URL to the homepage of the service provider
* @type {string | null}
*/
homepage: spObj.about.homepage || null
}
this.about = serviceProviderObject.about
/**
* What the profile would look like if the match is correct
* @property {object}
* What the profile would look like if a claim matches this service provider
* @type {Types.ServiceProviderProfile}
*/
this.profile = {
/**
* Profile name to be displayed
* @type {string}
*/
display: spObj.profile.display,
/**
* URI or URL for public access to the profile
* @type {string}
*/
uri: spObj.profile.uri,
/**
* URI or URL associated with the profile usually served as a QR code
* @type {string | null}
*/
qr: spObj.profile.qr || null
}
this.profile = serviceProviderObject.profile
/**
* Details from the claim matching process
* @property {object}
* Information about the claim matching process
* @type {Types.ServiceProviderClaim}
*/
this.claim = {
/**
* Regular expression used to parse the URI
* @type {string}
*/
uriRegularExpression: spObj.claim.uriRegularExpression,
/**
* Whether this match automatically excludes other matches
* @type {boolean}
*/
uriIsAmbiguous: spObj.claim.uriIsAmbiguous
}
this.claim = serviceProviderObject.claim
/**
* Information for the proof verification process
* @property {object}
* @type {Types.ServiceProviderProof}
*/
this.proof = {
/**
* Details to request the potential proof
* @property {object}
*/
request: {
/**
* Location of the proof
* @type {string | null}
*/
uri: spObj.proof.request.uri,
/**
* Fetcher to be used to request the proof
* @type {string}
*/
fetcher: spObj.proof.request.fetcher,
/**
* Type of access restriction
* @type {ProofAccessRestriction}
*/
accessRestriction: spObj.proof.request.accessRestriction,
/**
* Data needed by the fetcher or proxy to request the proof
* @type {object}
*/
data: spObj.proof.request.data
},
/**
* Details about the expected response
* @property {object}
*/
response: {
/**
* Expected format of the proof
* @type {ProofFormat}
*/
format: spObj.proof.response.format
},
/**
* Details about the target located in the response
* @type {ProofTarget[]}
*/
target: spObj.proof.target
}
this.proof = serviceProviderObject.proof
}
/**
* Get a JSON representation of the ServiceProvider object
* Get a JSON representation of the {@link ServiceProvider}
* @function
* @returns {object}
* @returns {Types.ServiceProviderObject} JSON representation of a {@link ServiceProvider}
*/
toJSON () {
return {

4
src/serviceProviders/activitypub.js
View file

@ -21,8 +21,8 @@ export const reURI = /^https:\/\/(.*)\/?/
/**
* @function
* @param {string} uri
* @returns {ServiceProvider}
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
return new ServiceProvider({

3
src/serviceProviders/aspe.js
View file

@ -21,7 +21,8 @@ export const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

4
src/serviceProviders/discourse.js
View file

@ -20,8 +20,8 @@ export const reURI = /^https:\/\/(.*)\/u\/(.*)\/?/
/**
* @function
* @param {string} uri
* @returns {ServiceProvider}
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/dns.js
View file

@ -20,7 +20,8 @@ export const reURI = /^dns:([a-zA-Z0-9.\-_]*)(?:\?(.*))?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/forem.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/forgejo.js
View file

@ -21,7 +21,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/gitea.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/github.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/gist\.github\.com\/(.*)\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

4
src/serviceProviders/gitlab.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/gitlab_proof\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)
@ -41,7 +42,6 @@ export function processURI (uri) {
uriIsAmbiguous: true
},
proof: {
uri,
request: {
fetcher: E.Fetcher.HTTP,
accessRestriction: E.ProofAccessRestriction.NONE,

3
src/serviceProviders/hackernews.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/news\.ycombinator\.com\/user\?id=(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/irc.js
View file

@ -20,7 +20,8 @@ export const reURI = /^irc:\/\/(.*)\/([a-zA-Z0-9\-[\]\\`_^{|}]*)/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/keybase.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/keybase.io\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/liberapay.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/liberapay\.com\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/lichess.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/lichess\.org\/@\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/lobsters.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/lobste\.rs\/(?:~|u\/)(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/matrix.js
View file

@ -20,7 +20,8 @@ export const reURI = /^matrix:u\/(?:@)?([^@:]*:[^?]*)(\?.*)?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/opencollective.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/opencollective\.com\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/openpgp.js
View file

@ -24,7 +24,8 @@ const reURIWkdAdvanced = /^https:\/\/(openpgpkey.*)\/.well-known\/openpgpkey\/(.
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
let reURI = null

3
src/serviceProviders/orcid.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/orcid\.org\/(.*)\/?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/owncast.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/reddit.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(?:www\.)?reddit\.com\/user\/(.*)\/comments\/(.
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/stackexchange.js
View file

@ -21,7 +21,8 @@ const reStackExchange = /\.stackexchange$/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const [, domain, id] = uri.match(reURI)

3
src/serviceProviders/telegram.js
View file

@ -20,7 +20,8 @@ export const reURI = /https:\/\/t.me\/([A-Za-z0-9_]{5,32})\?proof=([A-Za-z0-9_]{
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/twitter.js
View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/twitter\.com\/(.*)\/status\/([0-9]*)(?:\?.*)?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

3
src/serviceProviders/xmpp.js
View file

@ -20,7 +20,8 @@ export const reURI = /^xmpp:([a-zA-Z0-9.\-_]*)@([a-zA-Z0-9.\-_]*)(?:\?(.*))?/
/**
* @function
* @param {string} uri
* @param {string} uri - Claim URI to process
* @returns {ServiceProvider} The service provider information based on the claim URI
*/
export function processURI (uri) {
const match = uri.match(reURI)

2
src/signatures.js
View file

@ -28,7 +28,7 @@ import { Persona } from './persona.js'
* Extract the profile from a signature and fetch the associated key
* @async
* @param {string} signature - The plaintext signature to parse
* @returns {Promise<Profile>}
* @returns {Promise<Profile>} The profile obtained from the signature
*/
export async function parse (signature) {
/** @type {CleartextMessage} */

199
src/types.js Normal file
View file

@ -0,0 +1,199 @@
/*
Copyright 2024 Yarmo Mackenbach
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/**
* Contains various types
* @module types
*/
import { PublicKey } from 'openpgp'
import * as joseMod from 'jose'
import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestriction, ProofFormat, ProxyPolicy, PublicKeyEncoding, PublicKeyFetchMethod, PublicKeyType } from './enums.js'
/**
* Service provider
* @typedef {object} ServiceProviderObject
* @property {ServiceProviderAbout} about - Details about the service provider
* @property {ServiceProviderProfile} profile - What the profile would look like if a claim matches this service provider
* @property {ServiceProviderClaim} claim - Details from the claim matching process
* @property {ServiceProviderProof} proof - Information for the proof verification process
*/
/**
* Details about the service provider
* @typedef {object} ServiceProviderAbout
* @property {string} id - Identifier of the service provider (no whitespace or symbols, lowercase)
* @property {string} name - Full name of the service provider
* @property {string} [homepage] - URL to the homepage of the service provider
*/
/**
* What the profile would look like if a claim matches this service provider
* @typedef {object} ServiceProviderProfile
* @property {string} display - Profile name to be displayed
* @property {string} uri - URI or URL for public access to the profile
* @property {string} [qr] -URI or URL associated with the profile usually served as a QR code
*/
/**
* Information about the claim matching process
* @typedef {object} ServiceProviderClaim
* @property {string} uriRegularExpression - Regular expression used to parse the URI
* @property {boolean} uriIsAmbiguous - Whether this match automatically excludes other matches
*/
/**
* Information for the proof verification process
* @typedef {object} ServiceProviderProof
* @property {ServiceProviderProofRequest} request - Details to request the potential proof
* @property {ServiceProviderProofResponse} response - Details about the expected response
* @property {ProofTarget[]} target - Details about the target located in the response
*/
/**
* Details to request the potential proof
* @typedef {object} ServiceProviderProofRequest
* @property {string} [uri] - Location of the proof
* @property {string} fetcher - Fetcher to be used to request the proof
* @property {ProofAccessRestriction} accessRestriction - Type of access restriction
* @property {object} data - Data needed by the fetcher or proxy to request the proof
*/
/**
* Details about the expected response
* @typedef {object} ServiceProviderProofResponse
* @property {ProofFormat} format - Expected format of the proof
*/
/**
* Public key for a profile
* @typedef {object} ProfilePublicKey
* @property {PublicKeyType} keyType - The type of cryptographic key
* @property {PublicKeyEncoding} encoding - The encoding of the cryptographic key
* @property {string} [fingerprint] - The fingerprint of the cryptographic key
* @property {string} [encodedKey] - The encoded cryptographic key
* @property {PublicKey | joseMod.JWK} [key] - The raw cryptographic key as object (to be removed during toJSON())
* @property {ProfilePublicKeyFetch} fetch - Details on how to fetch the public key
*/
/**
* Details on how to fetch the public key
* @typedef {object} ProfilePublicKeyFetch
* @property {PublicKeyFetchMethod} method - The method to fetch the key
* @property {string} [query] - The query to fetch the key
* @property {string} [resolvedUrl] - The URL the method eventually resolved to
*/
/**
* Config used for the claim verification
* @typedef {object} VerificationConfig
* @property {ProxyVerificationConfig} [proxy] - Options related to the use of proxy servers
* @property {ClaimVerificationConfig} [claims] - Config related to the verification of supported claims
*/
/**
* Config related to the use of proxy servers
* @typedef {object} ProxyVerificationConfig
* @property {string} [scheme] - The scheme to use for proxy requests
* @property {string} [hostname] - The hostname of the proxy
* @property {ProxyPolicy} policy - The policy that defines when to use a proxy ({@link module:enums~ProxyPolicy|here})
*/
/**
* Config related to the verification of supported claims
* @typedef {object} ClaimVerificationConfig
* @property {ActivityPubClaimVerificationConfig} [activitypub] - Config related to the verification of ActivityPub claims
* @property {IrcClaimVerificationConfig} [irc] - Config related to the verification of IRC claims
* @property {MatrixClaimVerificationConfig} [matrix] - Config related to the verification of Matrix claims
* @property {TelegramClaimVerificationConfig} [telegram] - Config related to the verification of Telegram claims
* @property {XmppClaimVerificationConfig} [xmpp] - Config related to the verification of XMPP claims
*/
/**
* Config related to the verification of ActivityPub claims
* @typedef {object} ActivityPubClaimVerificationConfig
* @property {string} url - The URL of the verifier account
* @property {string} privateKey - The private key to sign the request
*/
/**
* Config related to the verification of IRC claims
* @typedef {object} IrcClaimVerificationConfig
* @property {string} nick - The nick that the library uses to connect to the IRC server
*/
/**
* Config related to the verification of Matrix claims
* @typedef {object} MatrixClaimVerificationConfig
* @property {string} instance - The server hostname on which the library can log in
* @property {string} accessToken - The access token required to identify the library ({@link https://www.matrix.org/docs/guides/client-server-api|Matrix docs})
*/
/**
* Config related to the verification of Telegram claims
* @typedef {object} TelegramClaimVerificationConfig
* @property {string} token - The Telegram API's token ({@link https://core.telegram.org/bots/api#authorizing-your-bot|Telegram docs})
*/
/**
* Config related to the verification of XMPP claims
* @typedef {object} XmppClaimVerificationConfig
* @property {string} service - The server hostname on which the library can log in
* @property {string} username - The username used to log in
* @property {string} password - The password used to log in
*/
/**
* The online verifier instance of identity profiles like Keyoxide's web interface
* @typedef {object} ProfileVerifier
* @property {string} name - Name of the profile verifier
* @property {string} url - URL to the profile verifier
*/
/**
* Parameters needed to perform the proof verification
* @typedef {object} VerificationParams
* @property {string} target - Proof to search
* @property {ClaimFormat} claimFormat - Format of the claim
* @property {EntityEncodingFormat} proofEncodingFormat - Encoding of the data containing the proof
* @property {ClaimRelation} [claimRelation] - How to find the proof inside the JSON data
*/
/**
* Result of the proof verification
* @typedef {object} VerificationResult
* @property {boolean} result - Whether the proof was found and the claim verified
* @property {boolean} completed - Whether the verification process completed without errors
* @property {VerificationResultProof} [proof] - Details about the proof and how it was fetched
* @property {any[]} errors - Errors that ocurred during the verification process
*/
/**
* Information about the proof in the proof verification result
* @typedef {object} VerificationResultProof
* @property {string} fetcher - Which fetcher was used to obtain the data containing the proof
* @property {boolean} viaProxy - Whether a proxy was used to obtain the data containing the proof
*/
/**
* The method to find the proof inside the response data
* @typedef {object} ProofTarget
* @property {ClaimFormat} format - How the response data is formatted
* @property {EntityEncodingFormat} encoding - How the response data is encoded
* @property {ClaimRelation} relation - How the proof is related to the response data
* @property {string[]} path - Path to the proof inside the response data object
*/
export const Types = {}

24
src/utils.js
View file

@ -15,6 +15,7 @@ limitations under the License.
*/
import isFQDN from 'validator/lib/isFQDN.js'
import { ClaimFormat } from './enums.js'
import * as Types from './types.js'
/**
* @module utils
@ -22,13 +23,10 @@ import { ClaimFormat } from './enums.js'
/**
* Generate an URL to request data from a proxy server
* @param {string} type - The name of the fetcher the proxy must use
* @param {object} data - The data the proxy must provide to the fetcher
* @param {object} opts - Options to enable the request
* @param {object} opts.proxy - Proxy related options
* @param {object} opts.proxy.scheme - The scheme used by the proxy server
* @param {object} opts.proxy.hostname - The hostname of the proxy server
* @returns {string}
* @param {string} type - The name of the fetcher the proxy must use
* @param {object} data - The data the proxy must provide to the fetcher
* @param {Types.VerificationConfig} opts - Options to enable the request
* @returns {string} Generated proxy URL
*/
export function generateProxyURL (type, data, opts) {
try {
@ -43,7 +41,7 @@ export function generateProxyURL (type, data, opts) {
queryStrings.push(`${key}=${encodeURIComponent(data[key])}`)
})
const scheme = opts.proxy.scheme ? opts.proxy.scheme : 'https'
const scheme = opts.proxy.scheme ?? 'https'
return `${scheme}://${opts.proxy.hostname}/api/3/get/${type}?${queryStrings.join(
'&'
@ -52,9 +50,9 @@ export function generateProxyURL (type, data, opts) {
/**
* Generate the string that must be found in the proof to verify a claim
* @param {string} fingerprint - The fingerprint of the claim
* @param {string} format - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat})
* @returns {string}
* @param {string} fingerprint - The fingerprint of the claim
* @param {ClaimFormat} format - The claim's format (see {@link ClaimFormat})
* @returns {string} Generate claim
*/
export function generateClaim (fingerprint, format) {
switch (format) {
@ -72,8 +70,8 @@ export function generateClaim (fingerprint, format) {
/**
* Get the URIs from a string and return them as an array
* @param {string} text - The text that may contain URIs
* @returns {Array<string>}
* @param {string} text - The text that may contain URIs
* @returns {Array<string>} List of URIs extracted from input
*/
export function getUriFromString (text) {
const re = /((([A-Za-z0-9]+:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www\.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w\-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[.!/\\\w]*))?)/gi

54
src/verifications.js
View file

@ -18,6 +18,7 @@ import { ClaimFormat, EntityEncodingFormat, ClaimRelation, ProofFormat } from '.
import { bcryptVerify, argon2Verify } from 'hash-wasm'
import { decodeHTML, decodeXML } from 'entities'
import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/**
* @module verifications
@ -25,35 +26,11 @@ import { ServiceProvider } from './serviceProvider.js'
*/
/**
* Parameters needed to perform the proof verification
* @typedef {object} VerificationParams
* @property {string} target
* @property {ClaimFormat} claimFormat
* @property {EntityEncodingFormat} proofEncodingFormat
* @property {ClaimRelation} [claimRelation]
*/
/**
* Result of the proof verification
* @typedef {Object} VerificationResult
* @property {boolean} result
* @property {boolean} completed
* @property {VerificationResultProof} [proof]
* @property {any[]} errors
*/
/**
* Information about the proof in the proof verification result
* @typedef {Object} VerificationResultProof
* @property {string} fetcher
* @property {boolean} viaProxy
*/
/**
* Check if string contains the proof
* @function
* @param {string} data
* @param {VerificationParams} params
* @returns {Promise<boolean>}
* @param {string} data - Data potentially containing the proof
* @param {Types.VerificationParams} params - Verification parameters
* @returns {Promise<boolean>} Whether the proof was found in the string
*/
const containsProof = async (data, params) => {
const fingerprintFormatted = generateClaim(params.target, params.claimFormat)
@ -237,11 +214,12 @@ const containsProof = async (data, params) => {
}
/**
* Run a JSON object through the verification process
* @function
* @param {any} proofData
* @param {string[]} checkPath
* @param {VerificationParams} params
* @returns {Promise<boolean>}
* @param {any} proofData - Data potentially containing the proof
* @param {string[]} checkPath - Paths to check for proof
* @param {Types.VerificationParams} params - Verification parameters
* @returns {Promise<boolean>} Whether the proof was found in the object
*/
const runJSON = async (proofData, checkPath, params) => {
if (!proofData) {
@ -288,15 +266,15 @@ const runJSON = async (proofData, checkPath, params) => {
}
/**
* Run the verification by finding the formatted fingerprint in the proof
* Run the verification by searching for the proof in the fetched data
* @async
* @param {object} proofData - The proof data
* @param {ServiceProvider} claimData - The claim data
* @param {string} fingerprint - The fingerprint
* @returns {Promise<VerificationResult>}
* @param {object} proofData - The proof data
* @param {ServiceProvider} claimData - The claim data
* @param {string} fingerprint - The fingerprint
* @returns {Promise<Types.VerificationResult>} Result of the verification
*/
export async function run (proofData, claimData, fingerprint) {
/** @type {VerificationResult} */
/** @type {Types.VerificationResult} */
const res = {
result: false,
completed: false,

4
test/openpgp.test.js
View file

@ -129,9 +129,9 @@ describe('openpgp.fetchURI', () => {
})
describe('openpgp.fetchHKP', () => {
it('should be a function (2 arguments)', () => {
it('should be a function (1 required argument, 1 optional argument)', () => {
expect(openpgp.fetchHKP).to.be.a('function')
expect(openpgp.fetchHKP).to.have.length(2)
expect(openpgp.fetchHKP).to.have.length(1)
})
it('should return a Key object when provided a valid fingerprint', async () => {
expect(await openpgp.fetchHKP(pubKeyFingerprint)).to.be.instanceOf(