Mirrors/doipjs
1
0
Fork 1
mirror of https://codeberg.org/keyoxide/doipjs.git synced 2024-12-22 14:39:28 -07:00
Code Issues Projects Releases Packages Wiki Activity

feat: combine jsdoc with tsimport

Browse source
This commit is contained in:
Yarmo Mackenbach 2024-01-28 12:15:03 +01:00
parent deaa858345
commit fe6588dcbb
No known key found for this signature in database
GPG key ID: C248C28D432560ED
24 changed files with 50 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
jsdoc-lib.json
View file

@ -1,5 +1,8 @@
{
"plugins": ["plugins/markdown"],
"plugins": [
"plugins/markdown",
"node_modules/jsdoc-tsimport-plugin"
],
"source": {
"include": ["./src", "./README.md"]
},

1
package.json
View file

@ -51,6 +51,7 @@
"eslint-plugin-promise": "^6.1.1",
"husky": "^7.0.0",
"jsdoc": "^4.0.2",
"jsdoc-tsimport-plugin": "^1.0.5",
"license-check-and-add": "^4.0.3",
"lint-staged": "^11.0.0",
"minify": "^9.1",

11
src/asp.js
View file

@ -13,9 +13,8 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
import axios, * as axiosMod from 'axios'
import axios from 'axios'
import { decodeProtectedHeader, importJWK, compactVerify, calculateJwkThumbprint } from 'jose'
import * as joseMod from 'jose'
import { base32, base64url } from 'rfc4648'
import { Claim } from './claim.js'
import { Persona } from './persona.js'
@ -58,12 +57,12 @@ export async function fetchASPE (uri) {
responseType: 'text'
}
)
.then((/** @type {axiosMod.AxiosResponse} */ response) => {
.then((/** @type {import('axios').AxiosResponse} */ response) => {
if (response.status === 200) {
return response
}
})
.then((/** @type {axiosMod.AxiosResponse} */ response) => response.data)
.then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
} catch (e) {
throw new Error(`Error fetching Keybase key: ${e.message}`)
}
@ -170,9 +169,9 @@ export async function parseProfileJws (profileJws, uri) {
}
/**
* Compute the fingerprint for JWK keys
* Compute the fingerprint for {@link https://github.com/panva/jose/blob/main/docs/interfaces/types.JWK.md JWK} keys
* @function
* @param {joseMod.JWK} key - The JWK public key for which to compute the fingerprint
* @param {import('jose').JWK} key - The JWK public key for which to compute the fingerprint
* @returns {Promise<string>} The computed fingerprint
*/
export async function computeJwkFingerprint (key) {

5
src/claim.js
View file

@ -22,7 +22,6 @@ import { list, data as _data } from './serviceProviders/index.js'
import { opts as _opts } from './defaults.js'
import { ClaimStatus } from './enums.js'
import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/**
* @class
@ -217,7 +216,7 @@ export class Claim {
* regardless of the result.
* @async
* @function
* @param {Types.VerificationConfig} [opts] - Options for proxy, fetchers
* @param {import('./types').VerificationConfig} [opts] - Options for proxy, fetchers
*/
async verify (opts) {
if (this._status === ClaimStatus.INIT) {
@ -245,7 +244,7 @@ export class Claim {
let claimData = this._matches[index]
/** @type {Types.VerificationResult} */
/** @type {import('./types').VerificationResult} */
let verificationResult = null
let proofData = null
let proofFetchError

3
src/defaults.js
View file

@ -14,7 +14,6 @@ See the License for the specific language governing permissions and
limitations under the License.
*/
import { ProxyPolicy } from './enums.js'
import * as Types from './types.js'
/**
* Contains default values
@ -24,7 +23,7 @@ import * as Types from './types.js'
/**
* The default claim verification config used throughout the library
* @constant
* @type {Types.VerificationConfig}
* @type {import('./types').VerificationConfig}
*/
export const opts = {
proxy: {

3
src/fetcher/activitypub.js
View file

@ -26,7 +26,6 @@ import isURL from 'validator/lib/isURL.js'
import { isNode } from 'browser-or-node'
import crypto from 'crypto'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -43,7 +42,7 @@ export const timeout = 5000
* @param {object} data - Data used in the request
* @param {string} data.url - The URL of the account to verify
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched ActivityPub object
*/
export async function fn (data, opts) {

3
src/fetcher/aspe.js
View file

@ -24,7 +24,6 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js'
import { version } from '../constants.js'
import { parseProfileJws } from '../asp.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -43,7 +42,7 @@ const reURI = /^aspe:([a-zA-Z0-9.\-_]*):([a-zA-Z0-9]*)/
* @param {object} data - Data used in the request
* @param {string} data.aspeUri - ASPE URI of the targeted profile
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../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) {

3
src/fetcher/dns.js
View file

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

3
src/fetcher/graphql.js
View file

@ -23,7 +23,6 @@ limitations under the License.
import axios from 'axios'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -41,7 +40,7 @@ export const timeout = 5000
* @param {string} data.url - The URL pointing at the GraphQL HTTP endpoint
* @param {string} data.query - The GraphQL query to fetch the data containing the proof
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched GraphQL object
*/
export async function fn (data, opts) {

3
src/fetcher/http.js
View file

@ -24,7 +24,6 @@ limitations under the License.
import axios from 'axios'
import { ProofFormat } from '../enums.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -42,7 +41,7 @@ export const timeout = 5000
* @param {string} data.url - The URL pointing at targeted content
* @param {string} data.format - The format of the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../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) {

3
src/fetcher/irc.js
View file

@ -23,7 +23,6 @@ limitations under the License.
import irc from 'irc-upd'
import isAscii from 'validator/lib/isAscii.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -41,7 +40,7 @@ export const timeout = 20000
* @param {string} data.nick - The nick of the targeted account
* @param {string} data.domain - The domain on which the targeted account is registered
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<string[]>} The fetched proofs from an IRC account
*/
export async function fn (data, opts) {

3
src/fetcher/matrix.js
View file

@ -25,7 +25,6 @@ import axios from 'axios'
import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -43,7 +42,7 @@ export const timeout = 5000
* @param {string} data.eventId - The identifier of the targeted post
* @param {string} data.roomId - The identifier of the room containing the targeted post
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object>} The fetched Matrix object
*/
export async function fn (data, opts) {

3
src/fetcher/openpgp.js
View file

@ -33,7 +33,6 @@ import { readKey } from 'openpgp'
import { OpenPgpQueryProtocol } from '../enums.js'
import { version } from '../constants.js'
import { parsePublicKey } from '../openpgp.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -51,7 +50,7 @@ export const timeout = 5000
* @param {string} data.url - The URL pointing at targeted content
* @param {OpenPgpQueryProtocol} data.protocol - The protocol used to access the targeted content
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../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) {

3
src/fetcher/telegram.js
View file

@ -24,7 +24,6 @@ limitations under the License.
import axios from 'axios'
import isAscii from 'validator/lib/isAscii.js'
import { version } from '../constants.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -42,7 +41,7 @@ export const timeout = 5000
* @param {string} data.chat - Telegram public group name (slug)
* @param {string} data.user - Telegram username
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<object|string>} The fetched Telegram object
*/
export async function fn (data, opts) {

5
src/fetcher/xmpp.js
View file

@ -25,7 +25,6 @@ import { client, xml } from '@xmpp/client'
import debug from '@xmpp/debug'
import isFQDN from 'validator/lib/isFQDN.js'
import isAscii from 'validator/lib/isAscii.js'
import * as Types from '../types.js'
/**
* Default timeout after which the fetch is aborted
@ -43,7 +42,7 @@ let iqCaller = null
* @ignore
* @function
* @async
* @param {Types.XmppClaimVerificationConfig} params - XMPP claim verification config
* @param {import('../types').XmppClaimVerificationConfig} params - XMPP claim verification config
* @returns {Promise<object>} The fetched proofs from an XMPP account
*/
const xmppStart = async (params) => {
@ -74,7 +73,7 @@ const xmppStart = async (params) => {
* @param {object} data - Data used in the request
* @param {string} data.id - The identifier of the targeted account
* @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
* @param {Types.VerificationConfig} [opts] - Options used to enable the request
* @param {import('../types').VerificationConfig} [opts] - Options used to enable the request
* @returns {Promise<Array<string>>} The fetched proofs from an XMPP account
*/
export async function fn (data, opts) {

1
src/index.js
View file

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

6
src/openpgp.js
View file

@ -13,7 +13,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
import axios, * as axiosMod from 'axios'
import axios from 'axios'
import { isUri } from 'valid-url'
import { readKey, PublicKey } from 'openpgp'
import HKP from '@openpgp/hkp-client'
@ -128,12 +128,12 @@ export async function fetchKeybase (username, fingerprint) {
responseType: 'text'
}
)
.then((/** @type {axiosMod.AxiosResponse} */ response) => {
.then((/** @type {import('axios').AxiosResponse} */ response) => {
if (response.status === 200) {
return response
}
})
.then((/** @type {axiosMod.AxiosResponse} */ response) => response.data)
.then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
} catch (e) {
throw new Error(`Error fetching Keybase key: ${e.message}`)
}

5
src/profile.js
View file

@ -15,7 +15,6 @@ limitations under the License.
*/
import { PublicKeyFetchMethod, PublicKeyEncoding, PublicKeyType, ProfileType } from './enums.js'
import { Persona } from './persona.js'
import * as Types from './types.js'
/**
* @class
@ -64,7 +63,7 @@ export class Profile {
this.primaryPersonaIndex = personas.length > 0 ? 0 : -1
/**
* The cryptographic key associated with the profile
* @type {Types.ProfilePublicKey}
* @type {import('./types').ProfilePublicKey}
* @public
*/
this.publicKey = {
@ -81,7 +80,7 @@ export class Profile {
}
/**
* List of verifier URLs
* @type {Types.ProfileVerifier[]}
* @type {import('./types').ProfileVerifier[]}
* @public
*/
this.verifiers = []

3
src/proofs.js
View file

@ -18,7 +18,6 @@ import { fetcher } from './index.js'
import { generateProxyURL } from './utils.js'
import { ProxyPolicy, ProofAccessRestriction } from './enums.js'
import { ServiceProvider } from './serviceProvider.js'
import * as Types from './types.js'
/**
* @module proofs
@ -32,7 +31,7 @@ import * as Types from './types.js'
* approach is possible.
* @async
* @param {ServiceProvider} data - Data from a claim definition
* @param {Types.VerificationConfig} opts - Options to enable the request
* @param {import('./types').VerificationConfig} opts - Options to enable the request
* @returns {Promise<object|string>} Fetched proof data
*/
export async function fetch (data, opts) {

13
src/serviceProvider.js
View file

@ -13,7 +13,6 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
import * as Types from './types.js'
/**
* A service provider matched to an identity claim
@ -22,27 +21,27 @@ import * as Types from './types.js'
*/
export class ServiceProvider {
/**
* @param {Types.ServiceProviderObject} serviceProviderObject - JSON representation of a {@link ServiceProvider}
* @param {import('./types').ServiceProviderObject} serviceProviderObject - JSON representation of a {@link ServiceProvider}
*/
constructor (serviceProviderObject) {
/**
* Details about the service provider
* @type {Types.ServiceProviderAbout}
* @type {import('./types').ServiceProviderAbout}
*/
this.about = serviceProviderObject.about
/**
* What the profile would look like if a claim matches this service provider
* @type {Types.ServiceProviderProfile}
* @type {import('./types').ServiceProviderProfile}
*/
this.profile = serviceProviderObject.profile
/**
* Information about the claim matching process
* @type {Types.ServiceProviderClaim}
* @type {import('./types').ServiceProviderClaim}
*/
this.claim = serviceProviderObject.claim
/**
* Information for the proof verification process
* @type {Types.ServiceProviderProof}
* @type {import('./types').ServiceProviderProof}
*/
this.proof = serviceProviderObject.proof
}
@ -50,7 +49,7 @@ export class ServiceProvider {
/**
* Get a JSON representation of the {@link ServiceProvider}
* @function
* @returns {Types.ServiceProviderObject} JSON representation of a {@link ServiceProvider}
* @returns {import('./types').ServiceProviderObject} JSON representation of a {@link ServiceProvider}
*/
toJSON () {
return {

8
src/types.js
View file

@ -18,9 +18,7 @@ limitations under the License.
* @module types
*/
import { PublicKey } from 'openpgp'
import * as joseMod from 'jose'
import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestriction, ProofFormat, ProxyPolicy, PublicKeyEncoding, PublicKeyFetchMethod, PublicKeyType } from './enums.js'
import { PublicKeyType, PublicKeyEncoding, PublicKeyFetchMethod, ProxyPolicy, ClaimFormat, EntityEncodingFormat, ClaimRelation, ProofAccessRestriction, ProofFormat } from './enums'
/**
* Service provider
@ -84,7 +82,7 @@ import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestrictio
* @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 {import('openpgp').PublicKey | import('jose').JWK} [key] - The raw cryptographic key as object (to be removed during toJSON())
* @property {ProfilePublicKeyFetch} fetch - Details on how to fetch the public key
*/
@ -108,7 +106,7 @@ import { ClaimFormat, ClaimRelation, EntityEncodingFormat, ProofAccessRestrictio
* @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})
* @property {ProxyPolicy} policy - The policy that defines when to use a proxy
*/
/**

5
src/utils.js
View file

@ -15,7 +15,6 @@ limitations under the License.
*/
import isFQDN from 'validator/lib/isFQDN.js'
import { ClaimFormat } from './enums.js'
import * as Types from './types.js'
/**
* @module utils
@ -25,7 +24,7 @@ import * as Types from './types.js'
* Generate an URL to request data from a proxy server
* @param {string} type - The name of the fetcher the proxy must use
* @param {object} data - The data the proxy must provide to the fetcher
* @param {Types.VerificationConfig} opts - Options to enable the request
* @param {import('./types').VerificationConfig} opts - Options to enable the request
* @returns {string} Generated proxy URL
*/
export function generateProxyURL (type, data, opts) {
@ -51,7 +50,7 @@ export function generateProxyURL (type, data, opts) {
/**
* Generate the string that must be found in the proof to verify a claim
* @param {string} fingerprint - The fingerprint of the claim
* @param {ClaimFormat} format - The claim's format (see {@link ClaimFormat})
* @param {ClaimFormat} format - The claim's format
* @returns {string} Generate claim
*/
export function generateClaim (fingerprint, format) {

9
src/verifications.js
View file

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

5
yarn.lock
View file

@ -2834,6 +2834,11 @@ js2xmlparser@^4.0.2:
dependencies:
xmlcreate "^2.0.4"
jsdoc-tsimport-plugin@^1.0.5:
version "1.0.5"
resolved "https://registry.yarnpkg.com/jsdoc-tsimport-plugin/-/jsdoc-tsimport-plugin-1.0.5.tgz#a329f48a01c307747931cca81aa856f51bf49c26"
integrity sha512-6mvyF+tXdanf3zxEumTF9Uf/sXGlANP+XohSuiJiOVVWPGxi+3f2a2sy5Ew3W+0PMYUkcGYNxfYd5mMZsIHQpg==
jsdoc-type-pratt-parser@~4.0.0:
version "4.0.0"
resolved "https://registry.yarnpkg.com/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz#136f0571a99c184d84ec84662c45c29ceff71114"