fix: fix jsdoc errors found by eslint

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

View file

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

View file

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

View file

@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License. limitations under the License.
*/ */
import { ProxyPolicy } from './enums.js' import { ProxyPolicy } from './enums.js'
import * as Types from './types.js'
/** /**
* Contains default values * Contains default values
@ -21,26 +22,9 @@ import { ProxyPolicy } from './enums.js'
*/ */
/** /**
* The default options used throughout the library * The default claim verification config used throughout the library
* @constant {object} * @constant
* @property {object} proxy - Options related to the proxy * @type {Types.VerificationConfig}
* @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
*/ */
export const opts = { export const opts = {
proxy: { proxy: {

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 * @readonly
* @enum {string} * @enum {string}
*/ */

View file

@ -18,7 +18,13 @@ import isURL from 'validator/lib/isURL.js'
import { isNode } from 'browser-or-node' import { isNode } from 'browser-or-node'
import crypto from 'crypto' import crypto from 'crypto'
import { version } from '../constants.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 export const timeout = 5000
/** /**
@ -28,12 +34,8 @@ export const timeout = 5000
* @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 {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {object} opts.claims * @returns {Promise<object>} The fetched ActivityPub object
* @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>}
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -17,7 +17,13 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js' import isFQDN from 'validator/lib/isFQDN.js'
import { version } from '../constants.js' import { version } from '../constants.js'
import { parseProfileJws } from '../asp.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 export const timeout = 5000
const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/ const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
@ -29,7 +35,8 @@ const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
* @param {object} data - Data used in the request * @param {object} data - Data used in the request
* @param {string} data.aspeUri - ASPE URI of the targeted profile * @param {string} data.aspeUri - ASPE URI of the targeted profile
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>} * @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) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -15,7 +15,13 @@ limitations under the License.
*/ */
import { isBrowser } from 'browser-or-node' import { isBrowser } from 'browser-or-node'
import dns from 'dns' import dns from 'dns'
import * as Types from '../types.js'
/**
* Timeout after which the fetch is aborted
* @constant
* @type {number}
*/
export const timeout = 5000 export const timeout = 5000
/** /**
@ -25,7 +31,8 @@ export const timeout = 5000
* @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
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object>} * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched DNS records
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
if (isBrowser) { if (isBrowser) {

View file

@ -15,7 +15,13 @@ limitations under the License.
*/ */
import axios from 'axios' import axios from 'axios'
import { version } from '../constants.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 export const timeout = 5000
/** /**
@ -26,7 +32,8 @@ export const timeout = 5000
* @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
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>} * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched GraphQL object
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -16,7 +16,13 @@ limitations under the License.
import axios from 'axios' import axios from 'axios'
import { ProofFormat } from '../enums.js' import { ProofFormat } from '../enums.js'
import { version } from '../constants.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 export const timeout = 5000
/** /**
@ -27,7 +33,8 @@ export const timeout = 5000
* @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
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>} * @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) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -15,7 +15,13 @@ limitations under the License.
*/ */
import irc from 'irc-upd' import irc from 'irc-upd'
import isAscii from 'validator/lib/isAscii.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 = 20000 export const timeout = 20000
/** /**
@ -26,11 +32,8 @@ export const timeout = 20000
* @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 {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {object} opts.claims * @returns {Promise<string[]>} The fetched proofs from an IRC account
* @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>}
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -17,7 +17,13 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js' import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.js' import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.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 export const timeout = 5000
/** /**
@ -28,12 +34,8 @@ export const timeout = 5000
* @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 {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {object} opts.claims * @returns {Promise<object>} The fetched Matrix object
* @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>}
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -18,7 +18,13 @@ import { readKey } from 'openpgp'
import { OpenPgpQueryProtocol } from '../enums.js' import { OpenPgpQueryProtocol } from '../enums.js'
import { version } from '../constants.js' import { version } from '../constants.js'
import { parsePublicKey } from '../openpgp.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 export const timeout = 5000
/** /**
@ -29,7 +35,8 @@ export const timeout = 5000
* @param {string} data.url - The URL pointing at targeted content * @param {string} data.url - The URL pointing at targeted content
* @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content * @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @returns {Promise<object|string>} * @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) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -16,7 +16,13 @@ limitations under the License.
import axios from 'axios' import axios from 'axios'
import isAscii from 'validator/lib/isAscii.js' import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.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 export const timeout = 5000
/** /**
@ -27,11 +33,8 @@ export const timeout = 5000
* @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 {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {object} opts.claims * @returns {Promise<object|string>} The fetched Telegram object
* @param {object} opts.claims.telegram
* @param {string} opts.claims.telegram.token - The Telegram Bot API token
* @returns {Promise<object|string>}
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
let timeoutHandle let timeoutHandle

View file

@ -17,18 +17,31 @@ import { client, xml } from '@xmpp/client'
import debug from '@xmpp/debug' import debug from '@xmpp/debug'
import isFQDN from 'validator/lib/isFQDN.js' import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.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 export const timeout = 5000
let xmpp = null let xmpp = null
let iqCaller = 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) => { return new Promise((resolve, reject) => {
const xmpp = client({ const xmpp = client({
service, service: params.service,
username, username: params.username,
password password: params.password
}) })
if (process.env.NODE_ENV !== 'production') { if (process.env.NODE_ENV !== 'production') {
debug(xmpp, true) debug(xmpp, true)
@ -51,13 +64,8 @@ const xmppStart = async (service, username, password) => {
* @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 {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {object} opts - Options used to enable the request * @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {object} opts.claims * @returns {Promise<Array<string>>} The fetched proofs from an XMPP account
* @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>}
*/ */
export async function fn (data, opts) { export async function fn (data, opts) {
try { try {
@ -69,11 +77,7 @@ export async function fn (data, opts) {
} }
if (!xmpp || xmpp.status !== 'online') { if (!xmpp || xmpp.status !== 'online') {
const xmppStartRes = await xmppStart( const xmppStartRes = await xmppStart(opts.claims.xmpp)
opts.claims.xmpp.service,
opts.claims.xmpp.username,
opts.claims.xmpp.password
)
xmpp = xmppStartRes.xmpp xmpp = xmppStartRes.xmpp
iqCaller = xmppStartRes.iqCaller iqCaller = xmppStartRes.iqCaller
} }

View file

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

View file

@ -32,16 +32,15 @@ import { Persona } from './persona.js'
* Fetch a public key using keyservers * Fetch a public key using keyservers
* @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] - Domain of the keyserver
* @returns {Promise<Profile>} * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @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');
* const key3 = doip.keys.fetchHKP('123abc123abc', 'pgpkeys.eu');
*/ */
export async function fetchHKP (identifier, keyserverDomain) { export async function fetchHKP (identifier, keyserverDomain = 'keys.openpgp.org') {
const keyserverBaseUrl = keyserverDomain const keyserverBaseUrl = `https://${keyserverDomain ?? 'keys.openpgp.org'}`
? `https://${keyserverDomain}`
: 'https://keys.openpgp.org'
const hkp = new HKP(keyserverBaseUrl) const hkp = new HKP(keyserverBaseUrl)
const lookupOpts = { const lookupOpts = {
@ -76,7 +75,7 @@ export async function fetchHKP (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 {Promise<Profile>} * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example * @example
* const key = doip.keys.fetchWKD('alice@domain.tld'); * const key = doip.keys.fetchWKD('alice@domain.tld');
*/ */
@ -115,7 +114,7 @@ export async function fetchWKD (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 {Promise<Profile>} * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @example * @example
* const key = doip.keys.fetchKeybase('alice', '123abc123abc'); * 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 * @function
* @param {string} rawKeyContent - Plaintext ASCII-formatted public key data * @param {string} rawKeyContent - Plaintext ASCII-formatted public key data
* @returns {Promise<Profile>} * @returns {Promise<Profile>} The profile from the armored public key
* @example * @example
* const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK----- * const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
* *
@ -185,7 +184,7 @@ export async function fetchPlaintext (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 {Promise<Profile>} * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @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');
@ -231,7 +230,7 @@ export async function fetchURI (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 {Promise<Profile>} * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
* @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');
@ -273,7 +272,7 @@ export async function fetch (identifier) {
* Process a public key to get a profile * Process a public key to get a profile
* @function * @function
* @param {PublicKey} publicKey - The public key to parse * @param {PublicKey} publicKey - The public key to parse
* @returns {Promise<Profile>} * @returns {Promise<Profile>} The profile from the processed OpenPGP key
* @example * @example
* const key = doip.keys.fetchURI('hkp:alice@domain.tld'); * const key = doip.keys.fetchURI('hkp:alice@domain.tld');
* const profile = doip.keys.parsePublicKey(key); * const profile = doip.keys.parsePublicKey(key);

View file

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

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

View file

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

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 See the License for the specific language governing permissions and
limitations under the License. limitations under the License.
*/ */
import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestriction, ProofFormat } from "./enums" import * as Types from './types.js'
/**
* 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
*/
/** /**
* A service provider matched to an identity claim * A service provider matched to an identity claim
* @class * @class
* @constructor
* @public * @public
*/ */
export class ServiceProvider { 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 * Details about the service provider
* @property {object} * @type {Types.ServiceProviderAbout}
*/ */
this.about = { this.about = serviceProviderObject.about
/** /**
* Identifier of the service provider (no whitespace or symbols, lowercase) * What the profile would look like if a claim matches this service provider
* @type {string} * @type {Types.ServiceProviderProfile}
*/ */
id: spObj.about.id, this.profile = serviceProviderObject.profile
/** /**
* Full name of the service provider * Information about the claim matching process
* @type {string} * @type {Types.ServiceProviderClaim}
*/ */
name: spObj.about.name, this.claim = serviceProviderObject.claim
/**
* URL to the homepage of the service provider
* @type {string | null}
*/
homepage: spObj.about.homepage || null
}
/**
* What the profile would look like if the match is correct
* @property {object}
*/
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
}
/**
* Details from the claim matching process
* @property {object}
*/
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
}
/** /**
* Information for the proof verification process * Information for the proof verification process
* @property {object} * @type {Types.ServiceProviderProof}
*/ */
this.proof = { this.proof = serviceProviderObject.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
}
} }
/** /**
* Get a JSON representation of the ServiceProvider object * Get a JSON representation of the {@link ServiceProvider}
* @function * @function
* @returns {object} * @returns {Types.ServiceProviderObject} JSON representation of a {@link ServiceProvider}
*/ */
toJSON () { toJSON () {
return { return {

View file

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

View file

@ -21,7 +21,8 @@ export const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

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

View file

@ -20,7 +20,8 @@ export const reURI = /^dns:([a-zA-Z0-9.\-_]*)(?:\?(.*))?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -21,7 +21,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/gist\.github\.com\/(.*)\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)\/(.*)\/gitlab_proof\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)
@ -41,7 +42,6 @@ export function processURI (uri) {
uriIsAmbiguous: true uriIsAmbiguous: true
}, },
proof: { proof: {
uri,
request: { request: {
fetcher: E.Fetcher.HTTP, fetcher: E.Fetcher.HTTP,
accessRestriction: E.ProofAccessRestriction.NONE, accessRestriction: E.ProofAccessRestriction.NONE,

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/news\.ycombinator\.com\/user\?id=(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^irc:\/\/(.*)\/([a-zA-Z0-9\-[\]\\`_^{|}]*)/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/keybase.io\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/liberapay\.com\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/lichess\.org\/@\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/lobste\.rs\/(?:~|u\/)(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^matrix:u\/(?:@)?([^@:]*:[^?]*)(\?.*)?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/opencollective\.com\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -24,7 +24,8 @@ const reURIWkdAdvanced = /^https:\/\/(openpgpkey.*)\/.well-known\/openpgpkey\/(.
/** /**
* @function * @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) { export function processURI (uri) {
let reURI = null let reURI = null

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/orcid\.org\/(.*)\/?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(.*)/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/(?:www\.)?reddit\.com\/user\/(.*)\/comments\/(.
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -21,7 +21,8 @@ const reStackExchange = /\.stackexchange$/
/** /**
* @function * @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) { export function processURI (uri) {
const [, domain, id] = uri.match(reURI) const [, domain, id] = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /https:\/\/t.me\/([A-Za-z0-9_]{5,32})\?proof=([A-Za-z0-9_]{
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^https:\/\/twitter\.com\/(.*)\/status\/([0-9]*)(?:\?.*)?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

@ -20,7 +20,8 @@ export const reURI = /^xmpp:([a-zA-Z0-9.\-_]*)@([a-zA-Z0-9.\-_]*)(?:\?(.*))?/
/** /**
* @function * @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) { export function processURI (uri) {
const match = uri.match(reURI) const match = uri.match(reURI)

View file

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

View file

@ -15,6 +15,7 @@ limitations under the License.
*/ */
import isFQDN from 'validator/lib/isFQDN.js' import isFQDN from 'validator/lib/isFQDN.js'
import { ClaimFormat } from './enums.js' import { ClaimFormat } from './enums.js'
import * as Types from './types.js'
/** /**
* @module utils * @module utils
@ -24,11 +25,8 @@ import { ClaimFormat } from './enums.js'
* Generate an URL to request data from a proxy server * Generate an URL to request data from a proxy server
* @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 {Types.VerificationConfig} opts - Options to enable the request
* @param {object} opts.proxy - Proxy related options * @returns {string} Generated proxy URL
* @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}
*/ */
export function generateProxyURL (type, data, opts) { export function generateProxyURL (type, data, opts) {
try { try {
@ -43,7 +41,7 @@ export function generateProxyURL (type, data, opts) {
queryStrings.push(`${key}=${encodeURIComponent(data[key])}`) 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( return `${scheme}://${opts.proxy.hostname}/api/3/get/${type}?${queryStrings.join(
'&' '&'
@ -53,8 +51,8 @@ export function 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 {string} format - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat}) * @param {ClaimFormat} format - The claim's format (see {@link ClaimFormat})
* @returns {string} * @returns {string} Generate claim
*/ */
export function generateClaim (fingerprint, format) { export function generateClaim (fingerprint, format) {
switch (format) { switch (format) {
@ -73,7 +71,7 @@ export function 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>} List of URIs extracted from input
*/ */
export function getUriFromString (text) { 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 const re = /((([A-Za-z0-9]+:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www\.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w\-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[.!/\\\w]*))?)/gi

View file

@ -18,6 +18,7 @@ import { ClaimFormat, EntityEncodingFormat, ClaimRelation, ProofFormat } from '.
import { bcryptVerify, argon2Verify } from 'hash-wasm' import { bcryptVerify, argon2Verify } from 'hash-wasm'
import { decodeHTML, decodeXML } from 'entities' import { decodeHTML, decodeXML } from 'entities'
import { ServiceProvider } from './serviceProvider.js' import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/** /**
* @module verifications * @module verifications
@ -25,35 +26,11 @@ import { ServiceProvider } from './serviceProvider.js'
*/ */
/** /**
* Parameters needed to perform the proof verification * Check if string contains the proof
* @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
*/
/**
* @function * @function
* @param {string} data * @param {string} data - Data potentially containing the proof
* @param {VerificationParams} params * @param {Types.VerificationParams} params - Verification parameters
* @returns {Promise<boolean>} * @returns {Promise<boolean>} Whether the proof was found in the string
*/ */
const containsProof = async (data, params) => { const containsProof = async (data, params) => {
const fingerprintFormatted = generateClaim(params.target, params.claimFormat) 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 * @function
* @param {any} proofData * @param {any} proofData - Data potentially containing the proof
* @param {string[]} checkPath * @param {string[]} checkPath - Paths to check for proof
* @param {VerificationParams} params * @param {Types.VerificationParams} params - Verification parameters
* @returns {Promise<boolean>} * @returns {Promise<boolean>} Whether the proof was found in the object
*/ */
const runJSON = async (proofData, checkPath, params) => { const runJSON = async (proofData, checkPath, params) => {
if (!proofData) { 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 * @async
* @param {object} proofData - The proof data * @param {object} proofData - The proof data
* @param {ServiceProvider} claimData - The claim data * @param {ServiceProvider} claimData - The claim data
* @param {string} fingerprint - The fingerprint * @param {string} fingerprint - The fingerprint
* @returns {Promise<VerificationResult>} * @returns {Promise<Types.VerificationResult>} Result of the verification
*/ */
export async function run (proofData, claimData, fingerprint) { export async function run (proofData, claimData, fingerprint) {
/** @type {VerificationResult} */ /** @type {Types.VerificationResult} */
const res = { const res = {
result: false, result: false,
completed: false, completed: false,

View file

@ -129,9 +129,9 @@ describe('openpgp.fetchURI', () => {
}) })
describe('openpgp.fetchHKP', () => { 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.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 () => { it('should return a Key object when provided a valid fingerprint', async () => {
expect(await openpgp.fetchHKP(pubKeyFingerprint)).to.be.instanceOf( expect(await openpgp.fetchHKP(pubKeyFingerprint)).to.be.instanceOf(