js: Add jsdoc, update webpack-cli dependency
--
* package.json:
- the old webpack-cli version depended on two packages
with vulnerabilities, set to minimum version 3.0.8 to fix this
(nodesecurity.io/advisories/157, nodesecurity.io/advisories/612)
- added License identifier
* README: Updated documentation
* jsdoc.conf: Added a configuration file for jsdoc
* some minor documentation changes, indentations
This commit is contained in:
Maximilian Krambach
parent
1105fc87a3
commit
1919fa41b6
@ -3,50 +3,80 @@ of gnupg in browsers, with the help of nativeMessaging.
|
||||
|
||||
Installation
|
||||
-------------
|
||||
gpgmejs uses webpack, and thus depends on nodejs for building. Webpack can be
|
||||
installed by running
|
||||
`npm install webpack webpack-cli --save-dev`.
|
||||
gpgmejs uses webpack, and thus depends on nodejs for building. All dependencies
|
||||
will be installed (in a local subdirectory) with the command `npm install`.
|
||||
|
||||
To create a current version of the package, the command is
|
||||
`npx webpack --config webpack.conf.js`.
|
||||
If you want a more debuggable (i.e. not minified) build, just change the mode
|
||||
in webpack.conf.js.
|
||||
|
||||
Demo WebExtension:
|
||||
As soon as a bundled webpack is in dist/
|
||||
the gpgmejs folder can just be included in the extensions tab of the browser in
|
||||
questions (extension debug mode needs to be active). For chrome, selecting the
|
||||
folder is sufficient, for firefox, the manifest.json needs to be selected.
|
||||
Demo and Test WebExtension:
|
||||
---------------------------
|
||||
|
||||
The Demo Extension shows simple examples of the usage of gpgmejs.
|
||||
|
||||
The BrowsertestExtension runs more intensive tests (using the mocha and chai
|
||||
frameworks). Tests from BrowserTestExtension/tests will be run against the
|
||||
gpgmejs.bundle.js itself. They aim to test the outward facing functionality
|
||||
and API.
|
||||
|
||||
Unittests as defined in ./unittests.js will be bundled in
|
||||
gpgmejs_unittests.bundle.js, and test the separate components of gpgmejs,
|
||||
which mostly are not exported.
|
||||
|
||||
. The file `build_extension.sh` may serve as a pointer on how to
|
||||
build and assemble these two Extensions and their dependencies. It can directly
|
||||
be used in most linux systems.
|
||||
|
||||
The resulting folders can just be included in the extensions tab of the browser
|
||||
in questions (extension debug mode needs to be active). For chrome, selecting
|
||||
the folder is sufficient, for firefox, the manifest.json needs to be selected.
|
||||
Please note that it is just for demonstration/debug purposes!
|
||||
|
||||
For the Extensions to successfully communicate with gpgme-json, a manifest file
|
||||
is needed.
|
||||
|
||||
- `~/.config/chromium/NativeMessagingHosts/gpgmejson.json`
|
||||
|
||||
In the browsers' nativeMessaging configuration folder a file 'gpgmejs.json'
|
||||
is needed, with the following content:
|
||||
|
||||
(The path to the native app gpgme-json may need adaption)
|
||||
- For Chrome/Chromium:
|
||||
```
|
||||
{
|
||||
"name": "gpgmejson",
|
||||
"description": "This is a test application for gpgmejs",
|
||||
"path": "/usr/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_origins": ["chrome-extension://ExtensionIdentifier/"]
|
||||
}
|
||||
```
|
||||
The usual path for Linux is similar to:
|
||||
`~/.config/chromium/NativeMessagingHosts/gpgmejson.json` for
|
||||
For Windows, the path to the manifest needs to be placed in
|
||||
`HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\gpgmejson`
|
||||
|
||||
Chromium:
|
||||
~/.config/chromium/NativeMessagingHosts/gpgmejson.json
|
||||
- For firefox:
|
||||
```
|
||||
{
|
||||
"name": "gpgmejson",
|
||||
"description": "This is a test application for gpgmejs",
|
||||
"path": "/usr/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_extensions": ["ExtensionIdentifier@temporary-addon"]
|
||||
}
|
||||
```
|
||||
|
||||
{
|
||||
"name": "gpgmejson",
|
||||
"description": "This is a test application for gpgmejs",
|
||||
"path": "/usr/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_origins": ["chrome-extension://ExtensionIdentifier/"]
|
||||
}
|
||||
The ExtensionIdentifier can be seen on the chrome://extensions page, and
|
||||
changes on each reinstallation. Note the slashes in allowed_origins.
|
||||
The ExtensionIdentifier can be seen as Extension ID on the about:addons page
|
||||
if addon-debugging is active. In firefox, the temporary addon is removed once
|
||||
firefox exits, and the identifier will need to be changed more often.
|
||||
|
||||
The manifest for linux is usually placed at:
|
||||
`~/.mozilla/native-messaging-hosts/gpgmejson.json`
|
||||
|
||||
Firefox:
|
||||
~/.mozilla/native-messaging-hosts/gpgmejson.json
|
||||
{
|
||||
"name": "gpgmejson",
|
||||
"description": "This is a test application for gpgmejs",
|
||||
"path": "/usr/bin/gpgme-json",
|
||||
"type": "stdio",
|
||||
"allowed_extensions": ["ExtensionIdentifier@temporary-addon"]
|
||||
}
|
||||
The ExtensionIdentifier can be seen as Extension ID on the about:addons page if
|
||||
addon-debugging is active. In firefox, the temporary addon is removed once
|
||||
firefox exits, and the identifier will need to be changed more often.
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
The documentation can be built by jsdoc. It currently uses the command
|
||||
`./node_modules/.bin/jsdoc -c jsdoc.conf`.
|
||||
|
||||
@ -1,14 +0,0 @@
|
||||
Test extension:
|
||||
|
||||
The test extension contains tests with mocha and chai. It will be packed as an
|
||||
extra extension (see build_extension.sh).
|
||||
|
||||
Tests from BrowserTestExtension/tests will be run against the gpgmejs.bundle.js
|
||||
itself. They aim to test the outward facing functionality and API.
|
||||
|
||||
Unittests as defined in ./unittests.js will be bundled in
|
||||
gpgmejs_unittests.bundle.js, and test the separate components of gpgmejs,
|
||||
which mostly are not exported.
|
||||
|
||||
The BrowserExtension can be installed the same way as the DemoExtension
|
||||
(see README).
|
||||
24
lang/js/jsdoc.conf
Normal file
24
lang/js/jsdoc.conf
Normal file
@ -0,0 +1,24 @@
|
||||
{
|
||||
"tags": {
|
||||
"allowUnknownTags": false,
|
||||
"dictionaries": ["jsdoc"]
|
||||
},
|
||||
"source": {
|
||||
"include": ["./src"],
|
||||
"includePattern": ".+\\.js(doc|x)?$",
|
||||
"excludePattern": "(^|\\/|\\\\)_"
|
||||
},
|
||||
"opts":{
|
||||
"destination": "./doc/",
|
||||
"recurse": true
|
||||
},
|
||||
"sourceType": "module",
|
||||
"plugins": [],
|
||||
"templates": {
|
||||
"cleverLinks": false,
|
||||
"monospaceLinks": false,
|
||||
"default": {
|
||||
"outputSourceFiles": true
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -6,11 +6,12 @@
|
||||
"private": true,
|
||||
"keywords": [],
|
||||
"author": "",
|
||||
"license": "",
|
||||
"license": "LGPL-2.1+",
|
||||
"devDependencies": {
|
||||
"webpack": "^4.5.0",
|
||||
"webpack-cli": "^2.0.14",
|
||||
"webpack-cli": "^3.0.8",
|
||||
"chai": "^4.1.2",
|
||||
"mocha": "^5.1.1"
|
||||
"mocha": "^5.1.1",
|
||||
"jsdoc": "^3.5.5"
|
||||
}
|
||||
}
|
||||
|
||||
@ -40,9 +40,10 @@ export class Connection{
|
||||
* Retrieves the information about the backend.
|
||||
* @param {Boolean} details (optional) If set to false, the promise will
|
||||
* just return a connection status
|
||||
* @returns {Promise<Object>}
|
||||
* {String} The property 'gpgme': Version number of gpgme
|
||||
* {Array<Object>} 'info' Further information about the backends.
|
||||
* @returns {Promise<Object>} result
|
||||
* @returns {String} result.gpgme Version number of gpgme
|
||||
* @returns {Array<Object>} result.info Further information about the
|
||||
* backends.
|
||||
* Example:
|
||||
* "protocol": "OpenPGP",
|
||||
* "fname": "/usr/bin/gpg",
|
||||
|
||||
@ -110,10 +110,10 @@ export class GPGME_Keyring {
|
||||
* contains a secret key.
|
||||
* @returns {Promise<GPGME_Key>}
|
||||
*
|
||||
* @async
|
||||
*
|
||||
* TODO: getHasSecret always returns false at this moment, so this fucntion
|
||||
* still does not fully work as intended.
|
||||
*
|
||||
* * @async
|
||||
*/
|
||||
getDefaultKey() {
|
||||
let me = this;
|
||||
@ -283,7 +283,7 @@ export class GPGME_Keyring {
|
||||
* @param {Date} expires (optional) Expiration date. If not set, expiration
|
||||
* will be set to 'never'
|
||||
*
|
||||
* @returns{Promise<Key>}
|
||||
* @return {Promise<Key>}
|
||||
*/
|
||||
generateKey(userId, algo = 'default', expires){
|
||||
if (
|
||||
|
||||
@ -19,17 +19,18 @@
|
||||
*
|
||||
* This is the configuration file for building the gpgmejs-Library with webpack
|
||||
*/
|
||||
/* global require, module, __dirname */
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
entry: './src/index.js',
|
||||
// mode: 'development',
|
||||
mode: 'production',
|
||||
output: {
|
||||
path: path.resolve(__dirname, 'build'),
|
||||
filename: 'gpgmejs.bundle.js',
|
||||
libraryTarget: 'var',
|
||||
libraryExport: 'default',
|
||||
library: 'Gpgmejs'
|
||||
}
|
||||
entry: './src/index.js',
|
||||
// mode: 'development',
|
||||
mode: 'production',
|
||||
output: {
|
||||
path: path.resolve(__dirname, 'build'),
|
||||
filename: 'gpgmejs.bundle.js',
|
||||
libraryTarget: 'var',
|
||||
libraryExport: 'default',
|
||||
library: 'Gpgmejs'
|
||||
}
|
||||
};
|
||||
|
||||
@ -19,16 +19,18 @@
|
||||
*
|
||||
* This is the configuration file for building the gpgmejs-Library with webpack
|
||||
*/
|
||||
/* global require, module, __dirname */
|
||||
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
entry: './unittests.js',
|
||||
mode: 'production',
|
||||
output: {
|
||||
path: path.resolve(__dirname, 'build'),
|
||||
filename: 'gpgmejs_unittests.bundle.js',
|
||||
libraryTarget: 'var',
|
||||
libraryExport: 'default',
|
||||
library: 'Gpgmejs_test'
|
||||
}
|
||||
entry: './unittests.js',
|
||||
mode: 'production',
|
||||
output: {
|
||||
path: path.resolve(__dirname, 'build'),
|
||||
filename: 'gpgmejs_unittests.bundle.js',
|
||||
libraryTarget: 'var',
|
||||
libraryExport: 'default',
|
||||
library: 'Gpgmejs_test'
|
||||
}
|
||||
};
|
||||
|
||||
Loading…
Reference in New Issue
Block a user