doipjs/src/claim.js

331 lines
9 KiB
JavaScript
Raw Normal View History

2021-04-16 05:11:27 -06:00
/*
Copyright 2021 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.
*/
const validator = require('validator')
const validUrl = require('valid-url')
const mergeOptions = require('merge-options')
const proofs = require('./proofs')
const verifications = require('./verifications')
const claimDefinitions = require('./claimDefinitions')
const defaults = require('./defaults')
const E = require('./enums')
/**
* @class
2021-04-22 07:14:21 -06:00
* @classdesc OpenPGP-based identity claim
* @property {string} uri - The claim's URI
* @property {string} fingerprint - The fingerprint to verify the claim against
* @property {string} status - The current status of the claim
* @property {Array<object>} matches - The claim definitions matched against the URI
2021-04-30 07:32:34 -06:00
* @property {object} verification - The result of the verification process
2021-04-16 05:11:27 -06:00
*/
class Claim {
/**
* Initialize a Claim object
* @constructor
* @param {string|object} [uri] - The URI of the identity claim or a JSONified Claim instance
2021-04-22 07:14:21 -06:00
* @param {string} [fingerprint] - The fingerprint of the OpenPGP key
* @example
* const claim = doip.Claim();
* const claim = doip.Claim('dns:domain.tld?type=TXT');
* const claim = doip.Claim('dns:domain.tld?type=TXT', '123abc123abc');
2021-04-30 07:32:34 -06:00
* const claimAlt = doip.Claim(JSON.stringify(claim));
2021-04-16 05:11:27 -06:00
*/
2021-07-09 15:44:52 -06:00
constructor (uri, fingerprint) {
2021-04-19 03:41:40 -06:00
// Import JSON
2021-04-19 05:38:00 -06:00
if (typeof uri === 'object' && 'claimVersion' in uri) {
const data = uri
2021-04-19 03:41:40 -06:00
switch (data.claimVersion) {
case 1:
2021-04-19 05:38:00 -06:00
this._uri = data.uri
this._fingerprint = data.fingerprint
2021-04-22 07:14:21 -06:00
this._status = data.status
2021-04-30 04:28:01 -06:00
this._matches = data.matches
2021-04-30 07:32:34 -06:00
this._verification = data.verification
2021-04-19 03:41:40 -06:00
break
2021-04-19 03:44:30 -06:00
2021-04-19 03:41:40 -06:00
default:
throw new Error('Invalid claim version')
}
return
}
2021-04-16 05:11:27 -06:00
// Verify validity of URI
if (uri && !validUrl.isUri(uri)) {
throw new Error('Invalid URI')
}
2021-04-22 08:00:37 -06:00
2021-04-16 05:11:27 -06:00
// Verify validity of fingerprint
if (fingerprint) {
try {
validator.isAlphanumeric(fingerprint)
} catch (err) {
2021-07-09 15:44:52 -06:00
throw new Error('Invalid fingerprint')
2021-04-16 05:11:27 -06:00
}
}
2022-11-17 13:09:42 -07:00
this._uri = uri || ''
this._fingerprint = fingerprint || ''
2021-04-22 07:14:21 -06:00
this._status = E.ClaimStatus.INIT
2022-11-17 13:09:42 -07:00
this._matches = []
this._verification = {}
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
get uri () {
2021-04-19 05:38:00 -06:00
return this._uri
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
get fingerprint () {
2021-04-19 05:38:00 -06:00
return this._fingerprint
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
get status () {
2021-04-22 07:14:21 -06:00
return this._status
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
get matches () {
2021-04-22 07:14:21 -06:00
if (this._status === E.ClaimStatus.INIT) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has not yet been matched')
}
2021-04-30 04:28:01 -06:00
return this._matches
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
get verification () {
2021-04-22 07:14:21 -06:00
if (this._status !== E.ClaimStatus.VERIFIED) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has not yet been verified')
}
2021-04-30 07:32:34 -06:00
return this._verification
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
set uri (uri) {
2021-04-22 07:14:21 -06:00
if (this._status !== E.ClaimStatus.INIT) {
2021-04-19 03:44:30 -06:00
throw new Error(
'Cannot change the URI, this claim has already been matched'
)
2021-04-16 05:11:27 -06:00
}
// Verify validity of URI
2022-11-17 13:09:42 -07:00
if (uri.length > 0 && !validUrl.isUri(uri)) {
2021-04-16 05:11:27 -06:00
throw new Error('The URI was invalid')
}
// Remove leading and trailing spaces
uri = uri.replace(/^\s+|\s+$/g, '')
2021-04-19 05:38:00 -06:00
this._uri = uri
2021-04-16 05:11:27 -06:00
}
2021-07-09 15:44:52 -06:00
set fingerprint (fingerprint) {
2021-04-22 07:14:21 -06:00
if (this._status === E.ClaimStatus.VERIFIED) {
2021-04-19 03:44:30 -06:00
throw new Error(
'Cannot change the fingerprint, this claim has already been verified'
)
2021-04-16 05:11:27 -06:00
}
2021-04-19 05:38:00 -06:00
this._fingerprint = fingerprint
2021-04-19 03:41:40 -06:00
}
2021-07-09 15:44:52 -06:00
set status (anything) {
2021-04-22 07:14:21 -06:00
throw new Error("Cannot change a claim's status")
2021-04-19 03:41:40 -06:00
}
2021-07-09 15:44:52 -06:00
set matches (anything) {
2021-04-30 04:28:01 -06:00
throw new Error("Cannot change a claim's matches")
2021-04-19 03:41:40 -06:00
}
2021-07-09 15:44:52 -06:00
set verification (anything) {
2021-04-30 04:28:01 -06:00
throw new Error("Cannot change a claim's verification result")
2021-04-16 05:11:27 -06:00
}
/**
* Match the claim's URI to candidate definitions
* @function
*/
2021-07-09 15:44:52 -06:00
match () {
2021-04-22 07:14:21 -06:00
if (this._status !== E.ClaimStatus.INIT) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim was already matched')
}
2022-11-17 13:09:42 -07:00
if (this._uri.length === 0 || !validUrl.isUri(this._uri)) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has no URI')
}
2021-04-30 04:28:01 -06:00
this._matches = []
2021-04-16 05:11:27 -06:00
claimDefinitions.list.every((name, i) => {
const def = claimDefinitions.data[name]
// If the candidate is invalid, continue matching
2021-04-19 05:38:00 -06:00
if (!def.reURI.test(this._uri)) {
2021-04-16 05:11:27 -06:00
return true
}
2021-04-19 05:38:00 -06:00
const candidate = def.processURI(this._uri)
2022-10-07 02:18:52 -06:00
// If the candidate could not be processed, continue matching
if (!candidate) {
return true
}
2021-04-16 05:11:27 -06:00
if (candidate.match.isAmbiguous) {
// Add to the possible candidates
2021-04-30 04:28:01 -06:00
this._matches.push(candidate)
2021-04-16 05:11:27 -06:00
} else {
// Set a single candidate and stop
2021-04-30 04:28:01 -06:00
this._matches = [candidate]
2021-04-16 05:11:27 -06:00
return false
}
// Continue matching
return true
})
2021-04-22 07:14:21 -06:00
this._status = E.ClaimStatus.MATCHED
2021-04-16 05:11:27 -06:00
}
/**
* Verify the claim. The proof for each candidate is sequentially fetched and
* checked for the fingerprint. The verification stops when either a positive
* result was obtained, or an unambiguous claim definition was processed
* regardless of the result.
* @async
* @function
* @param {object} [opts] - Options for proxy, fetchers
*/
2021-07-09 15:44:52 -06:00
async verify (opts) {
2021-04-22 07:14:21 -06:00
if (this._status === E.ClaimStatus.INIT) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has not yet been matched')
}
2021-04-22 07:14:21 -06:00
if (this._status === E.ClaimStatus.VERIFIED) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has already been verified')
}
2022-11-17 13:09:42 -07:00
if (this._fingerprint.length === 0) {
2021-04-16 05:11:27 -06:00
throw new Error('This claim has no fingerprint')
}
// Handle options
2021-07-09 15:44:52 -06:00
opts = mergeOptions(defaults.opts, opts || {})
2021-04-16 05:11:27 -06:00
2021-06-03 07:03:54 -06:00
// If there are no matches
if (this._matches.length === 0) {
this._verification = {
result: false,
completed: true,
proof: {},
2021-07-09 15:44:52 -06:00
errors: ['No matches for claim']
2021-06-03 07:03:54 -06:00
}
}
2021-04-16 05:11:27 -06:00
// For each match
2021-04-30 04:28:01 -06:00
for (let index = 0; index < this._matches.length; index++) {
2022-10-03 14:32:46 -06:00
let claimData = this._matches[index]
2021-04-19 03:44:30 -06:00
2021-07-09 15:44:52 -06:00
let verificationResult = null
let proofData = null
let proofFetchError
2021-04-16 05:11:27 -06:00
try {
proofData = await proofs.fetch(claimData, opts)
} catch (err) {
proofFetchError = err
}
if (proofData) {
// Run the verification process
2022-09-10 04:16:50 -06:00
verificationResult = await verifications.run(
2021-04-19 03:44:30 -06:00
proofData.result,
claimData,
2021-04-19 05:38:00 -06:00
this._fingerprint
2021-04-19 03:44:30 -06:00
)
2021-04-16 05:11:27 -06:00
verificationResult.proof = {
fetcher: proofData.fetcher,
2021-07-09 15:44:52 -06:00
viaProxy: proofData.viaProxy
2021-04-16 05:11:27 -06:00
}
2022-10-03 14:32:46 -06:00
// Post process the data
const def = claimDefinitions.data[claimData.serviceprovider.name]
if (def.functions && def.functions.postprocess) {
2022-10-25 01:22:25 -06:00
try {
({ claimData, proofData } = def.functions.postprocess(claimData, proofData))
2022-10-25 01:22:25 -06:00
} catch (_) {}
2022-10-03 14:32:46 -06:00
}
2021-04-16 05:11:27 -06:00
} else {
// Consider the proof completed but with a negative result
2021-07-09 15:44:52 -06:00
verificationResult = verificationResult || {
2021-04-16 05:11:27 -06:00
result: false,
completed: true,
proof: {},
2021-07-09 15:44:52 -06:00
errors: [proofFetchError]
2021-04-16 05:11:27 -06:00
}
2022-10-25 01:22:25 -06:00
}
2022-10-25 01:22:25 -06:00
if (this.isAmbiguous() && !verificationResult.result) {
// Assume a wrong match and continue
continue
2021-04-16 05:11:27 -06:00
}
if (verificationResult.completed) {
// Store the result, keep a single match and stop verifying
2021-04-30 07:32:34 -06:00
this._verification = verificationResult
2021-04-30 04:28:01 -06:00
this._matches = [claimData]
index = this._matches.length
2021-04-16 05:11:27 -06:00
}
}
// Fail safe verification result
2021-07-09 15:44:52 -06:00
this._verification = this._verification
? this._verification
: {
result: false,
completed: true,
proof: {},
2022-10-25 01:22:25 -06:00
errors: []
2021-07-09 15:44:52 -06:00
}
2021-04-22 07:14:21 -06:00
this._status = E.ClaimStatus.VERIFIED
2021-04-16 05:11:27 -06:00
}
/**
2021-04-22 07:14:21 -06:00
* Determine the ambiguity of the claim. A claim is only unambiguous if any
2021-04-16 05:11:27 -06:00
* of the candidates is unambiguous. An ambiguous claim should never be
* displayed in an user interface when its result is negative.
* @function
* @returns {boolean}
*/
2021-07-09 15:44:52 -06:00
isAmbiguous () {
2021-04-22 07:14:21 -06:00
if (this._status === E.ClaimStatus.INIT) {
2021-04-16 05:11:27 -06:00
throw new Error('The claim has not been matched yet')
}
2021-04-30 04:28:01 -06:00
if (this._matches.length === 0) {
2021-04-16 05:11:27 -06:00
throw new Error('The claim has no matches')
2021-04-19 03:44:30 -06:00
}
2021-07-09 15:44:52 -06:00
return this._matches.length > 1 || this._matches[0].match.isAmbiguous
2021-04-16 05:11:27 -06:00
}
/**
2021-04-19 03:44:30 -06:00
* Get a JSON representation of the Claim object. Useful when transferring
2021-04-16 05:11:27 -06:00
* data between instances/machines.
* @function
* @returns {object}
*/
2021-07-09 15:44:52 -06:00
toJSON () {
2021-04-16 05:11:27 -06:00
return {
claimVersion: 1,
2021-04-19 05:38:00 -06:00
uri: this._uri,
fingerprint: this._fingerprint,
2021-04-22 07:14:21 -06:00
status: this._status,
2021-04-30 04:28:01 -06:00
matches: this._matches,
2021-07-09 15:44:52 -06:00
verification: this._verification
2021-04-16 05:11:27 -06:00
}
}
}
2021-04-19 03:44:30 -06:00
module.exports = Claim