fix: fix and add missing JSDOC types

This commit is contained in:
Yarmo Mackenbach 2023-05-03 15:31:13 +02:00
parent fb0aaa3e17
commit 53e73afa19
No known key found for this signature in database
GPG key ID: 37367F4AF4087AD1
12 changed files with 67 additions and 24 deletions

View file

@ -33,10 +33,13 @@ module.exports.timeout = 5000
* @async * @async
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.url - The URL of the account to verify * @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 - 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.url - The URL of the verifier account
* @param {string} opts.claims.activitypub.privateKey - The private key to sign the request * @param {string} opts.claims.activitypub.privateKey - The private key to sign the request
* @returns {object} * @returns {Promise<object>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let crypto let crypto

View file

@ -34,7 +34,8 @@ if (jsEnv.isNode) {
* @async * @async
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.domain - The targeted domain * @param {string} data.domain - The targeted domain
* @returns {object} * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle

View file

@ -32,7 +32,8 @@ module.exports.timeout = 5000
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at the GraphQL HTTP endpoint * @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 {string} data.query - The GraphQL query to fetch the data containing the proof
* @returns {object|string} * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle

View file

@ -33,7 +33,8 @@ module.exports.timeout = 5000
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.url - The URL pointing at targeted content * @param {string} data.url - The URL pointing at targeted content
* @param {string} data.format - The format of the targeted content * @param {string} data.format - The format of the targeted content
* @returns {object|string} * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle

View file

@ -36,9 +36,12 @@ if (jsEnv.isNode) {
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.nick - The nick of the targeted account * @param {string} data.nick - The nick of the targeted account
* @param {string} data.domain - The domain on which the targeted account is registered * @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 - 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 * @param {string} opts.claims.irc.nick - The nick to be used by the library to log in
* @returns {object} * @returns {Promise<object>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle

View file

@ -33,10 +33,13 @@ module.exports.timeout = 5000
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.eventId - The identifier of the targeted post * @param {string} data.eventId - The identifier of the targeted post
* @param {string} data.roomId - The identifier of the room containing 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 - 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.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}) * @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 {object} * @returns {Promise<object>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle

View file

@ -34,9 +34,12 @@ module.exports.timeout = 5000
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.chat - Telegram public chat username * @param {string} data.chat - Telegram public chat username
* @param {string} data.user - Telegram user 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 - 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 * @param {string} opts.claims.telegram.token - The Telegram Bot API token
* @returns {object|string} * @returns {Promise<object|string>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
let timeoutHandle let timeoutHandle
@ -47,7 +50,7 @@ module.exports.fn = async (data, opts) => {
) )
}) })
const apiPromise = (method) => new Promise((resolve, reject) => { const apiPromise = (/** @type {string} */ method) => new Promise((resolve, reject) => {
try { try {
validator.isAscii(opts.claims.telegram.token) validator.isAscii(opts.claims.telegram.token)
} catch (err) { } catch (err) {

View file

@ -60,11 +60,14 @@ if (jsEnv.isNode) {
* @async * @async
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.id - The identifier of the targeted account * @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 - 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.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.username - The username used to log in
* @param {string} opts.claims.xmpp.password - The password used to log in * @param {string} opts.claims.xmpp.password - The password used to log in
* @returns {object} * @returns {Promise<object>}
*/ */
module.exports.fn = async (data, opts) => { module.exports.fn = async (data, opts) => {
try { try {

View file

@ -30,7 +30,7 @@ const Claim = require('./claim')
* @function * @function
* @param {string} identifier - Fingerprint or email address * @param {string} identifier - Fingerprint or email address
* @param {string} [keyserverDomain=keys.openpgp.org] - Domain of the keyserver * @param {string} [keyserverDomain=keys.openpgp.org] - Domain of the keyserver
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const key1 = doip.keys.fetchHKP('alice@domain.tld'); * const key1 = doip.keys.fetchHKP('alice@domain.tld');
* const key2 = doip.keys.fetchHKP('123abc123abc'); * const key2 = doip.keys.fetchHKP('123abc123abc');
@ -67,7 +67,7 @@ const fetchHKP = async (identifier, keyserverDomain) => {
* Fetch a public key using Web Key Directory * Fetch a public key using Web Key Directory
* @function * @function
* @param {string} identifier - Identifier of format 'username@domain.tld` * @param {string} identifier - Identifier of format 'username@domain.tld`
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const key = doip.keys.fetchWKD('alice@domain.tld'); * const key = doip.keys.fetchWKD('alice@domain.tld');
*/ */
@ -79,7 +79,7 @@ const fetchWKD = async (identifier) => {
const publicKey = await wkd const publicKey = await wkd
.lookup(lookupOpts) .lookup(lookupOpts)
.catch((error) => { .catch((/** @type {Error} */ error) => {
throw new Error(`Key does not exist or could not be fetched (${error})`) throw new Error(`Key does not exist or could not be fetched (${error})`)
}) })
@ -100,7 +100,7 @@ const fetchWKD = async (identifier) => {
* @function * @function
* @param {string} username - Keybase username * @param {string} username - Keybase username
* @param {string} fingerprint - Fingerprint of key * @param {string} fingerprint - Fingerprint of key
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const key = doip.keys.fetchKeybase('alice', '123abc123abc'); * const key = doip.keys.fetchKeybase('alice', '123abc123abc');
*/ */
@ -114,12 +114,12 @@ const fetchKeybase = async (username, fingerprint) => {
responseType: 'text' responseType: 'text'
} }
) )
.then((response) => { .then((/** @type {import('axios').AxiosResponse} */ response) => {
if (response.status === 200) { if (response.status === 200) {
return response return response
} }
}) })
.then((response) => response.data) .then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
} catch (e) { } catch (e) {
throw new Error(`Error fetching Keybase key: ${e.message}`) throw new Error(`Error fetching Keybase key: ${e.message}`)
} }
@ -136,7 +136,7 @@ const fetchKeybase = async (username, fingerprint) => {
* Get a public key from plaintext data * Get a public key from plaintext data
* @function * @function
* @param {string} rawKeyContent - Plaintext ASCII-formatted public key data * @param {string} rawKeyContent - Plaintext ASCII-formatted public key data
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK----- * const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
* *
@ -161,7 +161,7 @@ const fetchPlaintext = async (rawKeyContent) => {
* Fetch a public key using an URI * Fetch a public key using an URI
* @function * @function
* @param {string} uri - URI that defines the location of the key * @param {string} uri - URI that defines the location of the key
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const key1 = doip.keys.fetchURI('hkp:alice@domain.tld'); * const key1 = doip.keys.fetchURI('hkp:alice@domain.tld');
* const key2 = doip.keys.fetchURI('hkp:123abc123abc'); * const key2 = doip.keys.fetchURI('hkp:123abc123abc');
@ -207,7 +207,7 @@ const fetchURI = async (uri) => {
* This function will also try and parse the input as a plaintext key * This function will also try and parse the input as a plaintext key
* @function * @function
* @param {string} identifier - URI that defines the location of the key * @param {string} identifier - URI that defines the location of the key
* @returns {openpgp.PublicKey} * @returns {Promise<openpgp.PublicKey>}
* @example * @example
* const key1 = doip.keys.fetch('alice@domain.tld'); * const key1 = doip.keys.fetch('alice@domain.tld');
* const key2 = doip.keys.fetch('123abc123abc'); * const key2 = doip.keys.fetch('123abc123abc');
@ -251,7 +251,7 @@ const fetch = async (identifier) => {
* Process a public key to get user data and claims * Process a public key to get user data and claims
* @function * @function
* @param {openpgp.PublicKey} publicKey - The public key to process * @param {openpgp.PublicKey} publicKey - The public key to process
* @returns {object} * @returns {Promise<object>}
* @example * @example
* const key = doip.keys.fetchURI('hkp:alice@domain.tld'); * const key = doip.keys.fetchURI('hkp:alice@domain.tld');
* const data = doip.keys.process(key); * const data = doip.keys.process(key);

View file

@ -28,6 +28,7 @@ const keys = require('./keys')
* @returns {Promise<object>} * @returns {Promise<object>}
*/ */
const process = async (signature) => { const process = async (signature) => {
/** @type {openpgp.CleartextMessage} */
let sigData let sigData
const result = { const result = {
fingerprint: null, fingerprint: null,
@ -131,7 +132,7 @@ const process = async (signature) => {
let userData let userData
if (signersUserID) { if (signersUserID) {
result.key.data.users.forEach((user) => { result.key.data.users.forEach((/** @type {{ userID: { email: string; }; }} */ user) => {
if (user.userID.email === signersUserID) { if (user.userID.email === signersUserID) {
userData = user userData = user
} }

View file

@ -25,6 +25,7 @@ const E = require('./enums')
* @param {string} type - The name of the fetcher the proxy must use * @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} data - The data the proxy must provide to the fetcher
* @param {object} opts - Options to enable the request * @param {object} opts - Options to enable the request
* @param {object} opts.proxy - Proxy related options
* @param {object} opts.proxy.hostname - The hostname of the proxy server * @param {object} opts.proxy.hostname - The hostname of the proxy server
* @returns {string} * @returns {string}
*/ */
@ -49,7 +50,7 @@ const generateProxyURL = (type, data, opts) => {
/** /**
* Generate the string that must be found in the proof to verify a claim * Generate the string that must be found in the proof to verify a claim
* @param {string} fingerprint - The fingerprint of the claim * @param {string} fingerprint - The fingerprint of the claim
* @param {number} format - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat}) * @param {string} format - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat})
* @returns {string} * @returns {string}
*/ */
const generateClaim = (fingerprint, format) => { const generateClaim = (fingerprint, format) => {
@ -66,7 +67,7 @@ const generateClaim = (fingerprint, format) => {
/** /**
* Get the URIs from a string and return them as an array * Get the URIs from a string and return them as an array
* @param {string} text - The text that may contain URIs * @param {string} text - The text that may contain URIs
* @returns {Array.string} * @returns {Array<string>}
*/ */
const getUriFromString = (text) => { const getUriFromString = (text) => {
const re = /((([A-Za-z0-9]+:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www\.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w\-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[.!/\\\w]*))?)/gi const re = /((([A-Za-z0-9]+:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www\.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w\-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[.!/\\\w]*))?)/gi

View file

@ -23,6 +23,16 @@ const entities = require('entities')
* @ignore * @ignore
*/ */
/**
* @function
* @param {string} data
* @param {object} params
* @param {string} params.target
* @param {string} params.claimFormat
* @param {string} params.proofEncodingFormat
* @param {string} [params.claimRelation]
* @returns {Promise<boolean>}
*/
const containsProof = async (data, params) => { const containsProof = async (data, params) => {
const fingerprintFormatted = utils.generateClaim(params.target, params.claimFormat) const fingerprintFormatted = utils.generateClaim(params.target, params.claimFormat)
const fingerprintURI = utils.generateClaim(params.target, E.ClaimFormat.URI) const fingerprintURI = utils.generateClaim(params.target, E.ClaimFormat.URI)
@ -122,6 +132,7 @@ const containsProof = async (data, params) => {
if (result) continue if (result) continue
const candidate = uris[index] const candidate = uris[index]
/** @type {URL} */
let candidateURL let candidateURL
try { try {
@ -135,7 +146,8 @@ const containsProof = async (data, params) => {
} }
// Using fetch -> axios doesn't find the ariadne-identity-proof header // Using fetch -> axios doesn't find the ariadne-identity-proof header
const response = await fetch(candidate, { // eslint-disable-line /** @type {Response} */
const response = await fetch(candidate, {
method: 'HEAD' method: 'HEAD'
}) })
.catch(e => { .catch(e => {
@ -155,6 +167,17 @@ const containsProof = async (data, params) => {
return result return result
} }
/**
* @function
* @param {any} proofData
* @param {string} checkPath
* @param {object} params
* @param {string} params.target
* @param {string} params.claimFormat
* @param {string} params.proofEncodingFormat
* @param {string} [params.claimRelation]
* @returns {Promise<boolean>}
*/
const runJSON = async (proofData, checkPath, params) => { const runJSON = async (proofData, checkPath, params) => {
if (!proofData) { if (!proofData) {
return false return false
@ -205,7 +228,7 @@ const runJSON = async (proofData, checkPath, params) => {
* @param {object} proofData - The proof data * @param {object} proofData - The proof data
* @param {object} claimData - The claim data * @param {object} claimData - The claim data
* @param {string} fingerprint - The fingerprint * @param {string} fingerprint - The fingerprint
* @returns {object} * @returns {Promise<object>}
*/ */
const run = async (proofData, claimData, fingerprint) => { const run = async (proofData, claimData, fingerprint) => {
const res = { const res = {