Add derive function and passes proofSet option

lib/ProofSet.js

@@ -59,17 +59,78 @@ module.exports = class ProofSet {
 
  delete input.proof;
 
+ // get existing proof set, if any
+ const proofSet = _getProofs({document});
+
  // create the new proof (suites MUST output a proof using the security-v2
  // `@context`)
  const proof = await suite.createProof({
- document: input, purpose, documentLoader
+ document: input, purpose, proofSet, documentLoader
  });
 
  jsonld.addValue(document, 'proof', proof);
 
  return document;
  }
 
+ /**
+ * Derives a new Linked Data document with a new `proof` from an existing
+ * document with an existing proof set.
+ *
+ * Important note: This method assumes that the term `proof` in the given
+ * document has the same definition as the `https://w3id.org/security/v2`
+ * JSON-LD @context.
+ *
+ * @param document {object} - JSON-LD Document from which to derive a proof.
+ * @param options {object} Options hashmap.
+ *
+ * A `suite` option is required:
+ *
+ * @param options.suite {LinkedDataSignature} a signature suite instance
+ * that will derive the new document and new `proof`.
+ *
+ * A `purpose` option is required:
+ *
+ * @param options.purpose {ProofPurpose} a proof purpose instance that will
+ * augment the proof with information describing its intended purpose.
+ *
+ * Advanced optional parameters and overrides:
+ *
+ * @param [documentLoader] {function} a custom document loader,
+ * `Promise<RemoteDocument> documentLoader(url)`.
+ *
+ * @return {Promise<object>} resolves with the new document, with a new
+ * top-level `proof` property.
+ */
+ async derive(document, {suite, purpose, documentLoader} = {}) {
+ if(!suite) {
+ throw new TypeError('"options.suite" is required.');
+ }
+ if(!purpose) {
+ throw new TypeError('"options.purpose" is required.');
+ }
+
+ if(documentLoader) {
+ documentLoader = extendContextLoader(documentLoader);
+ } else {
+ documentLoader = strictDocumentLoader;
+ }
+
+ // shallow copy document to allow removal of existing proofs
+ const input = {...document};
+ delete input.proof;
+
+ // get existing proof set, if any
+ const proofSet = _getProofs({document});
+
+ // create the new document and proof
+ const newDocument = await suite.derive({
+ document: input, purpose, proofSet, documentLoader
+ });
+
+ return newDocument;
+ }
+
  /**
  * Verifies Linked Data proof(s) on a document. The proofs to be verified
  * must match the given proof purpose.
@@ -122,10 +183,13 @@ module.exports = class ProofSet {
  document = {...document};
 
  // get proofs from document
- const {proofSet, document: doc} = await _getProofs({
- document, documentLoader
- });
- document = doc;
+ const proofSet = _getProofs({document});
+ if(proofSet.length === 0) {
+ // no possible matches
+ throw new Error('No matching proofs found in the given document.');
+ }
+ // clear proofs from shallow copy
+ delete document.proof;
 
  // verify proofs
  const results = await _verify({
@@ -158,16 +222,10 @@ module.exports = class ProofSet {
  }
 };
 
-async function _getProofs({document}) {
+function _getProofs({document}) {
  // handle document preprocessing to find proofs
  let proofSet;
  proofSet = jsonld.getValues(document, 'proof');
- delete document.proof;
-
- if(proofSet.length === 0) {
- // no possible matches
- throw new Error('No matching proofs found in the given document.');
- }
 
  // shallow copy proofs and add document context or SECURITY_CONTEXT_URL
  const context = document['@context'] || constants.SECURITY_CONTEXT_URL;
@@ -176,7 +234,7 @@ async function _getProofs({document}) {
  ...proof
  }));
 
- return {proofSet, document};
+ return proofSet;
 }
 
 async function _verify({

lib/jsonld-signatures.js

@@ -15,6 +15,63 @@ Object.assign(api, constants);
 const ProofSet = require('./ProofSet');
 const VerificationError = require('./VerificationError');
 
+/**
+ * Derives a proof from the provided document, resulting in a new document
+ * with a new `proof` on it as generated by the given cryptographic suite.
+ *
+ * @param {object} document - The JSON-LD document from which to derive a
+ * new proof.
+ *
+ * @param {object} options - Options hashmap.
+ * @param {LinkedDataSignature} options.suite - The linked data signature
+ * cryptographic suite, containing private key material, with which to sign
+ * the document.
+ *
+ * @param {ProofPurpose} purpose - A proof purpose instance that will
+ * match proofs to be verified and ensure they were created according to
+ * the appropriate purpose.
+ *
+ * @param {function} documentLoader - A secure document loader (it is
+ * recommended to use one that provides static known documents, instead of
+ * fetching from the web) for returning contexts, controller documents, keys,
+ * and other relevant URLs needed for the proof.
+ *
+ * Advanced optional parameters and overrides:
+ *
+ * @param {function} [options.expansionMap] - NOT SUPPORTED; do not use.
+ * @param {boolean} [options.addSuiteContext=true] - Toggles the default
+ * behavior of each signature suite enforcing the presence of its own
+ * `@context` (if it is not present, it's added to the context list).
+ *
+ * @returns {Promise<object>} Resolves with signed document.
+ */
+api.derive = async function derive(document, {
+ suite, purpose, documentLoader, addSuiteContext = true
+} = {}) {
+ if(typeof document !== 'object') {
+ throw new TypeError('The "document" parameter must be an object.');
+ }
+ // Ensure document contains the signature suite specific context URL
+ // or throw an error (in case an advanced user overrides the
+ // `addSuiteContext` flag to false).
+ suite.ensureSuiteContext({document, addSuiteContext});
+
+ try {
+ return await new ProofSet().derive(
+ document, {suite, purpose, documentLoader});
+ } catch(e) {
+ if(!documentLoader && e.name === 'jsonld.InvalidUrl') {
+ const {details: {url}} = e;
+ const err = new Error(
+ `A URL "${url}" could not be fetched; you need to pass ` +
+ '"documentLoader" or resolve the URL before calling "derive".');
+ err.cause = e;
+ throw err;
+ }
+ throw e;
+ }
+};
+
 /**
  * Cryptographically signs the provided document by adding a `proof` section,
  * based on the provided suite and proof purpose.

lib/suites/LinkedDataProof.js

@@ -19,7 +19,7 @@ module.exports = class LinkedDataProof {
  * @returns {Promise<object>} Resolves with the created proof object.
  */
  async createProof({
- /* document, purpose, documentLoader */
+ /* document, purpose, proofSet, documentLoader */
  }) {
  throw new Error('"createProof" must be implemented in a derived class.');
  }

lib/suites/LinkedDataSignature.js

@@ -58,10 +58,12 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  * defaults to `now()`).
  * @param {boolean} [options.useNativeCanonize] - Whether to use a native
  * canonize algorithm.
+ * @param {object} [options.canonizeOptions] - Options to pass to
+ * canonize algorithm.
  */
  constructor({
  type, proof, LDKeyClass, date, key, signer, verifier, useNativeCanonize,
- contextUrl
+ canonizeOptions, contextUrl
  } = {}) {
  super({type});
  this.LDKeyClass = LDKeyClass;
@@ -72,6 +74,7 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  this.key = vm.key;
  this.signer = vm.signer;
  this.verifier = vm.verifier;
+ this.canonizeOptions = canonizeOptions;
  if(date) {
  this.date = new Date(date);
  if(isNaN(this.date)) {
@@ -83,13 +86,15 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  }
 
  /**
- * @param document {object} to be signed.
- * @param purpose {ProofPurpose}
- * @param documentLoader {function}
+ * @param {object} options - The options to use.
+ * @param {object} options.document - The document to be signed.
+ * @param {ProofPurpose} options.purpose - The proof purpose instance.
+ * @param {Array} options.proofSet - Any existing proof set.
+ * @param {function} options.documentLoader - The document loader to use.
  *
  * @returns {Promise<object>} Resolves with the created proof object.
  */
- async createProof({document, purpose, documentLoader}) {
+ async createProof({document, purpose, proofSet, documentLoader}) {
  // build proof (currently known as `signature options` in spec)
  let proof;
  if(this.proof) {
@@ -123,7 +128,7 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
 
  // add any extensions to proof (mostly for legacy support)
  proof = await this.updateProof({
- document, proof, purpose, documentLoader
+ document, proof, proofSet, purpose, documentLoader
  });
 
  // allow purpose to update the proof; the `proof` is in the
@@ -134,7 +139,7 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
 
  // create data to sign
  const verifyData = await this.createVerifyData({
- document, proof, documentLoader
+ document, proof, proofSet, documentLoader
  });
 
  // sign data
@@ -145,9 +150,9 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  }
 
  /**
- * @param document {object} to be signed.
- * @param purpose {ProofPurpose}
- * @param documentLoader {function}
+ * @param {object} options - The options to use.
+ * @param {object} options.proof - The proof to be updated.
+ * @param {Array} options.proofSet - Any existing proof set.
  *
  * @returns {Promise<object>} Resolves with the created proof object.
  */
@@ -157,17 +162,20 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  }
 
  /**
- * @param proof {object} the proof to be verified.
- * @param document {object} the document the proof applies to.
- * @param documentLoader {function}
+ * @param {object} options - The options to use.
+ * @param {object} options.proof - The proof to be verified.
+ * @param {object} options.document - The document the proof applies to.
+ * @param {ProofPurpose} options.purpose - The proof purpose instance.
+ * @param {Array} options.proofSet - Any existing proof set.
+ * @param {function} options.documentLoader - The document loader to use.
  *
  * @returns {Promise<{object}>} Resolves with the verification result.
  */
- async verifyProof({proof, document, documentLoader}) {
+ async verifyProof({proof, proofSet, document, documentLoader}) {
  try {
  // create data to verify
  const verifyData = await this.createVerifyData(
- {document, proof, documentLoader});
+ {document, proof, proofSet, documentLoader});
 
  // fetch verification method
  const verificationMethod = await this.getVerificationMethod(
@@ -190,10 +198,16 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  async canonize(input, {documentLoader, skipExpansion}) {
  return jsonld.canonize(input, {
  algorithm: 'URDNA2015',
+ // do not resolve any relative URLs or terms, throw errors instead
+ base: null,
  format: 'application/n-quads',
  documentLoader,
+ // throw errors if any values would be dropped due to missing
+ // definitions or relative URLs
+ safe: true,
  skipExpansion,
- useNative: this.useNativeCanonize
+ useNative: this.useNativeCanonize,
+ ...this.canonizeOptions
  });
  }
 
@@ -209,14 +223,17 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  delete proof.proofValue;
  return this.canonize(proof, {
  documentLoader,
- skipExpansion: false
+ skipExpansion: false,
+ ...this.canonizeOptions
  });
  }
 
  /**
- * @param document {object} to be signed/verified.
- * @param proof {object}
- * @param documentLoader {function}
+ * @param {object} options - The options to use.
+ * @param {object} options.document - The document to be signed/verified.
+ * @param {object} options.proof - The proof to be verified.
+ * @param {Array} options.proofSet - Any existing proof set.
+ * @param {function} options.documentLoader - The document loader to use.
  *
  * @returns {Promise<{Uint8Array}>}.
  */
@@ -250,9 +267,24 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  }
 
  /**
- * @param document {object} to be signed.
+ * @param verifyData {Uint8Array}.
+ * @param document {object} document from which to derive a new document
+ * and proof.
  * @param proof {object}
+ * @param proofSet {Array}
  * @param documentLoader {function}
+ *
+ * @returns {Promise<{object}>} The new document with `proof`.
+ */
+ async derive() {
+ throw new Error('Must be implemented by a derived class.');
+ }
+
+ /**
+ * @param proof {object}
+ * @param documentLoader {function}
+ *
+ * @returns {Promise<{object}>} The new document with `proof`.
  */
  async getVerificationMethod({proof, documentLoader}) {
  let {verificationMethod} = proof;
@@ -269,7 +301,7 @@ module.exports = class LinkedDataSignature extends LinkedDataProof {
  '@context': constants.SECURITY_CONTEXT_URL,
  '@embed': '@always',
  id: verificationMethod
- }, {documentLoader, compactToRelative: false});
+ }, {documentLoader, compactToRelative: false, safe: true});
  if(!framed) {
  throw new Error(`Verification method ${verificationMethod} not found.`);
  }