Reorganize suites for external signing/verification

.eslintrc

@@ -1,5 +1,6 @@
 {
   "env": {
+    "amd": true,
     "browser": true
   },
   "rules": {

.travis.yml

@@ -19,7 +19,8 @@ script:
 # only run karma tests for one node version
 matrix:
   include:
-  - node_js: "6"
+  - name: "Browser Unit Tests"
+    node_js: "6"
     env: BUNDLER=webpack
 #  - node_js: "6"
 #    env: BUNDLER=browserify

CHANGELOG.md

@@ -1,5 +1,27 @@
 # jsonld-signatures ChangeLog
 
+## 3.0.0 - TBD
+
+### Added
+- Add `compactProof` flag that can be set to `false` to enable skipping
+  compaction of proof(s) when it is known that the input document's (for `sign`
+  or `verify`) JSON-LD `@context` defines all applicable proof terms using the
+  same definitions as the JSON-LD `@context` used internally by the library
+  (i.e. the JSON-LD `@context` defined by `constants.SECURITY_CONTEXT_URL`).
+  This flag should only be set to `false` by advanced users that have ensured
+  their software systems have strictly validated the input to ensure that it
+  is safe and cannot be misinterpreted. If these guarantees can be met, then
+  setting this flag to `false` may be a useful optimization consideration.
+
+### Changed
+- **BREAKING**: `sign` and `verify` APIs require suites and proof purpose
+  instances to be passed.
+
+### Removed
+- **BREAKING**: Removed API `wrap` and injector support.
+- **BREAKING**: callback-based API is no longer supported.
+- **BREAKING**: Removed exposed utility/helper functions.
+
 ## 2.3.1 - 2018-09-05
 
 ### Changed

LICENSE

@@ -1,4 +1,5 @@
-Copyright (c) 2014-2017, Digital Bazaar, Inc.
+BSD 3-Clause License
+Copyright (c) 2010-2018 Digital Bazaar, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -9,6 +9,36 @@ This software works in all modern browsers as well as node.js via [npm](https://
 Introduction
 ------------
 
+A Linked Data Signature proof is created (or verified) by specifying a
+signature suite and a proof purpose.
+
+The signature suite performs the cryptographic operation required to sign (or
+verify) a digital signature and includes information in a proof such as the
+`verificationMethod` identifier (aka `creator`) and the date the proof was
+created (aka `created`).
+
+The proof purpose indicates why the proof was created and what its intended use
+is. This information can also be used to make sure that the
+`verificationMethod` was authorized for the stated purpose in the proof. Using
+a proof purpose helps to encourage people to authorize certain cryptographic
+keys (verification methods) for explicit purposes rather than granting them
+ambient authority. This approach can help prevent people from accidentally
+signing documents for reasons they did not intend.
+
+This library provides base classes for signature suites and proof purposes
+so that custom extensions can be written. It also provides some commonly
+used signature suites and proof purposes.
+
+This library also supports legacy signature suites such as `GraphSignature2012`,
+`LinkedDataSignature2015`, and `EcdsaKoblitzSignature2016`. These signature
+suites must be used with a `PublicKeyProofPurpose` instance as the proof
+purpose as they were created before extensible proof purposes were possible.
+
+During verification, the key and key controller information must be discovered.
+This library allows for the key and key controller information to be looked up
+via a `documentLoader` or it can be provided directly to the API via the
+signature suite or proof purpose, respectively.
+
 Install with npm:
 
 ```
@@ -17,9 +47,7 @@ npm install jsonld-signatures
 
 In Node.js, include the library like this:
 ```js
-var jsonld = require('jsonld');
-var jsig = require('jsonld-signatures');
-jsig.use('jsonld', jsonld);
+const jsigs = require('jsonld-signatures');
 ```
 
 In a browser environment, include `jsonld`, `forge`, and
@@ -28,33 +56,37 @@ In a browser environment, include `jsonld`, `forge`, and
 Examples
 --------
 
+Signing and verifying a simple assertion:
+
 ```js
 // to generate the next two lines, run the following command:
 //
 // openssl genrsa -out key.pem; cat key.pem; openssl rsa -in key.pem -pubout -out pubkey.pem; cat pubkey.pem; rm key.pem pubkey.pem
 //
 // for an example of how to specify these keys, look at [key-example]:
-var testPublicKeyPem = "-----BEGIN PUBLIC KEY-----\r\n...";
-var testPrivateKeyPem = "-----BEGIN PRIVATE KEY-----\r\n...";
+const publicKeyPem = "-----BEGIN PUBLIC KEY-----\r\n...";
+const privateKeyPem = "-----BEGIN PRIVATE KEY-----\r\n...";
 
 // specify the public key object
-var testPublicKey = {
-  '@context': jsig.SECURITY_CONTEXT_URL,
-  '@id': 'https://example.com/i/alice/keys/1',
-  owner: 'https://example.com/i/alice',
-  publicKeyPem: testPublicKeyPem
+const publicKey = {
+  '@context': jsigs.SECURITY_CONTEXT_URL,
+  id: 'https://example.com/i/alice/keys/1',
+  controller: 'https://example.com/i/alice',
+  publicKeyPem
 };
 
-// specify the public key owner object
-var testPublicKeyOwner = {
-  "@context": jsig.SECURITY_CONTEXT_URL,
-  '@id': 'https://example.com/i/alice',
-  publicKey: [testPublicKey]
+// specify the public key controller object
+const controller = {
+  '@context': jsigs.SECURITY_CONTEXT_URL,
+  id: 'https://example.com/i/alice',
+  publicKey: [publicKey]
+  // this authorizes this key to be used for making assertions
+  assertionMethod: [publicKey.id]
 };
 
 // create the JSON-LD document that should be signed
-var testDocument = {
-  "@context": {
+const doc = {
+  '@context': {
     schema: 'http://schema.org/',
     name: 'schema:name',
     homepage: 'schema:url',
@@ -65,40 +97,95 @@ var testDocument = {
   image: 'https://manu.sporny.org/images/manu.png'
 };
 
-// sign the document and then verify the signed document
-jsig.sign(testDocument, {
-  privateKeyPem: testPrivateKeyPem,
-  creator: 'https://example.com/i/alice/keys/1'
-}, function(err, signedDocument) {
-  if(err) {
-    return console.log('Signing error:', err);
-  }
-  console.log('Signed document:', signedDocument);
-
-  // verify the signed document
-  jsig.verify(signedDocument, {
-    publicKey: testPublicKey,
-    publicKeyOwner: testPublicKeyOwner,
-  }, function(err, verified) {
-    if(err) {
-      return console.log('Signature verification error:', err);
-    }
-    console.log('Signature is valid:', verified);
-  });
+// sign the document as a simple assertion
+const {RsaSignature2018} = jsigs.suites;
+const {AuthenticationProofPurpose} = jsigs.purposes;
+const {RSAKeyPair} = jsigs;
+const key = new RSAKeyPair({...publicKey, privateKeyPem});
+const signed = await jsigs.sign(doc, {
+  suite: new RsaSignature2018({key}),
+  purpose: new AssertionProofPurpose()
+});
+
+console.log('Signed document:', signed);
+
+// verify the signed document
+const result = await jsigs.verify(signed, {
+  suite: new RsaSignature2018(key),
+  purpose: new AssertionProofPurpose({controller})
 });
+if(result.verified) {
+  console.log('Signature verified.');
+} else {
+  console.log('Signature verification error:', result.error);
+}
+```
+
+Signing and verifying a document to authenticate to a website:
+
+```js
+const publicKeyBase58 = 'GycSSui454dpYRKiFdsQ5uaE8Gy3ac6dSMPcAoQsk8yq';
+const privateKeyBase58 = '3Mmk4UzTRJTEtxaKk61LxtgUxAa2Dg36jF6Vog...SSiF';
+
+// specify the public key object
+const publicKey = {
+  '@context': jsigs.SECURITY_CONTEXT_URL,
+  id: 'https://example.com/i/alice/keys/2',
+  controller: 'https://example.com/i/alice',
+  publicKeyBase58
+};
+
+// specify the public key controller object
+const controller = {
+  '@context': jsigs.SECURITY_CONTEXT_URL,
+  id: 'https://example.com/i/alice',
+  publicKey: [publicKey]
+  // this authorizes this key to be used for authenticating
+  authentication: [publicKey.id]
+};
+
+// create the JSON-LD document that should be signed
+const doc = {
+  '@context': {
+    schema: 'http://schema.org/',
+    name: 'schema:action'
+  },
+  action: 'AuthenticateMe'
+};
 
-// verification
-var sign = jsig.promises.sign(testDocument, {
-  privateKeyPem: testPrivateKeyPem,
-  creator: 'https://example.com/i/alice/keys/1'
+// sign the document for the purpose of authentication
+const {Ed25519Signature2018} = jsigs.suites;
+const {AuthenticationProofPurpose} = jsigs.purposes;
+const {Ed25519KeyPair} = jsigs;
+const signed = await jsigs.sign(doc, {
+  suite: new Ed25519Signature2018({
+    verificationMethod: publicKey.id,
+    key: new Ed25519KeyPair({privateKeyPem})
+  }),
+  purpose: new AuthenticationProofPurpose({
+    challenge: 'abc',
+    domain: 'example.com'
+  })
 });
-sign.then(function(signedDocument) {...}, function(err) {...});
 
-var verify = jsig.promises.verify(signedDocument, {
-  publicKey: testPublicKey,
-  publicKeyOwner: testPublicKeyOwner
+console.log('Signed document:', signed);
+
+// verify the signed document
+const result = await jsigs.verify(signed, {
+  suite: new Ed25519Signature2018({
+    key: new Ed25519KeyPair(publicKey)
+  }),
+  purpose: new AuthenticationProofPurpose({
+    controller,
+    challenge: 'abc',
+    domain: 'example.com'
+  })
 });
-verify.then(function(verified) {...}, function(err) {...});
+if(result.verified) {
+  console.log('Signature verified.');
+} else {
+  console.log('Signature verification error:', result.error);
+}
 ```
 
 Commercial Support

karma.conf.js

@@ -1,21 +1,15 @@
 /**
  * Karam configuration for jsonld-signatures.
  *
- * @author Dave Longley
- * @author David I. Lehn
- *
- * Copyright (c) 2011-2017 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2011-2018 Digital Bazaar, Inc. All rights reserved.
  */
-const path = require('path');
-const webpack = require('webpack');
-
 module.exports = function(config) {
   // bundler to test: webpack, browserify
-  var bundler = process.env.BUNDLER || 'webpack';
+  const bundler = process.env.BUNDLER || 'webpack';
 
-  var frameworks = ['mocha'];
+  const frameworks = ['mocha'];
   // main bundle preprocessors
-  var preprocessors = ['babel'];
+  const preprocessors = ['babel'];
 
   if(bundler === 'browserify') {
     frameworks.push(bundler);
@@ -33,7 +27,7 @@ module.exports = function(config) {
 
     // frameworks to use
     // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
-    frameworks: frameworks,
+    frameworks,
 
     // list of files / patterns to load in the browser
     files: [
@@ -62,15 +56,18 @@ module.exports = function(config) {
             include: [{
               // exclude node_modules by default
               exclude: /(node_modules)/
-            }, {
-              // include rdf-canonize
+            }/*, {
+              // include jsonld and rdf-canonize
               include: /(node_modules\/jsonld)/,
               include: /(node_modules\/rdf-canonize)/
-            }],
+            }*/],
             use: {
               loader: 'babel-loader',
               options: {
-                presets: ['env']
+                presets: ['env'],
+                plugins: [
+                  ['transform-object-rest-spread', {useBuiltIns: true}]
+                ]
               }
             }
           }
@@ -81,6 +78,13 @@ module.exports = function(config) {
         process: false,
         crypto: false,
         setImmediate: false
+      },
+      resolve: {
+        alias: {
+          'bitcore-message':
+            require.resolve('bitcore-message/dist/bitcore-message.js'),
+          jsonld: require.resolve('jsonld/dist/jsonld.js')
+        }
       }
     },
 
@@ -111,7 +115,7 @@ module.exports = function(config) {
     // start these browsers
     // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
     //browsers: ['PhantomJS', 'Chrome', 'Firefox', 'Safari'],
-    browsers: ['PhantomJS'],
+    browsers: ['ChromeHeadless'],
 
     customLaunchers: {
       IE9: {