nodemailer/wildduck
1
1
Fork 0
mirror of https://github.com/nodemailer/wildduck.git synced 2024-09-20 23:36:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

updated api docs

Browse source
This commit is contained in:
Andris Reinman 2017-11-28 15:45:43 +02:00
parent 839c336fac
commit 4a58568953
6 changed files with 131 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/api_data.js
View file

File diff suppressed because one or more lines are too long

2
docs/api_data.json
View file

File diff suppressed because one or more lines are too long

2
docs/api_project.js
View file

@ -1 +1 @@
define({ "name": "wildduck", "version": "1.0.0", "description": "WildDuck API docs. Under construction, see old docs here: https://github.com/nodemailer/wildduck/blob/master/docs/api.md", "title": "WildDuck API", "url": "http://localhost:8080", "sampleUrl": false, "defaultVersion": "0.0.0", "apidoc": "0.3.0", "generator": { "name": "apidoc", "time": "2017-11-28T13:13:57.125Z", "url": "http://apidocjs.com", "version": "0.17.6" } });
define({ "name": "wildduck", "version": "1.0.0", "description": "WildDuck API docs. Under construction, see old docs here: https://github.com/nodemailer/wildduck/blob/master/docs/api.md", "title": "WildDuck API", "url": "http://localhost:8080", "sampleUrl": false, "defaultVersion": "0.0.0", "apidoc": "0.3.0", "generator": { "name": "apidoc", "time": "2017-11-28T13:44:42.966Z", "url": "http://apidocjs.com", "version": "0.17.6" } });

2
docs/api_project.json
View file

@ -1 +1 @@
{ "name": "wildduck", "version": "1.0.0", "description": "WildDuck API docs. Under construction, see old docs here: https://github.com/nodemailer/wildduck/blob/master/docs/api.md", "title": "WildDuck API", "url": "http://localhost:8080", "sampleUrl": false, "defaultVersion": "0.0.0", "apidoc": "0.3.0", "generator": { "name": "apidoc", "time": "2017-11-28T13:13:57.125Z", "url": "http://apidocjs.com", "version": "0.17.6" } }
{ "name": "wildduck", "version": "1.0.0", "description": "WildDuck API docs. Under construction, see old docs here: https://github.com/nodemailer/wildduck/blob/master/docs/api.md", "title": "WildDuck API", "url": "http://localhost:8080", "sampleUrl": false, "defaultVersion": "0.0.0", "apidoc": "0.3.0", "generator": { "name": "apidoc", "time": "2017-11-28T13:44:42.966Z", "url": "http://apidocjs.com", "version": "0.17.6" } }

119
lib/api/auth.js
View file

@ -5,6 +5,60 @@ const MongoPaging = require('mongo-cursor-pagination-node6');
const ObjectID = require('mongodb').ObjectID;
module.exports = (db, server, userHandler) => {
/**
* @api {post} /authenticate Authenticate an User
* @apiName PostAuth
* @apiGroup Authentication
* @apiHeader {String} X-Access-Token Optional access token if authentication is enabled
* @apiHeaderExample {json} Header-Example:
* {
* "X-Access-Token": "59fc66a03e54454869460e45"
* }
*
* @apiParam {String} username Username or E-mail address
* @apiParam {String} password Password
* @apiParam {String} [protocol] Application identifier for security logs
* @apiParam {String} [scope="master"] Required scope. One of <code>master</code>, <code>imap</code>, <code>smtp</code>, <code>pop3</code>
* @apiParam {String} [sess] Session identifier for the logs
* @apiParam {String} [ip] IP address for the logs
*
* @apiSuccess {Boolean} success Indicates successful response
* @apiSuccess {String} id ID of authenticated User
* @apiSuccess {String} username Username of authenticated User
* @apiSuccess {String} scope The scope this authentication is valid for
* @apiSuccess {String[]} require2fa List of enabled 2FA mechanisms
* @apiSuccess {Boolean} requirePasswordChange Indicates if account hassword has been reset and should be replaced
*
* @apiError error Description of the error
*
* @apiExample {curl} Example usage:
* curl -i -XPOST http://localhost:8080/authenticate \
* -H 'Content-type: application/json' \
* -d '{
* "username": "myuser",
* "password": "secretpass",
* "scope": "master"
* }'
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "success": true,
* "id": "5a12914c350c183bd0d331f0",
* "username": "myuser",
* "scope": "master",
* "require2fa": [
* "totp"
* ],
* "requirePasswordChange": false
* }
*
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 200 OK
* {
* "error": "Authentication failed. Invalid scope"
* }
*/
server.post('/authenticate', (req, res, next) => {
res.charSet('utf-8');
@ -85,6 +139,71 @@ module.exports = (db, server, userHandler) => {
});
});
/**
* @api {get} /users/:user/authlog List authentication Events
* @apiName GetAuthlog
* @apiGroup Authentication
* @apiHeader {String} X-Access-Token Optional access token if authentication is enabled
* @apiHeaderExample {json} Header-Example:
* {
* "X-Access-Token": "59fc66a03e54454869460e45"
* }
*
* @apiParam {String} user ID of the User
* @apiParam {String} [action] Limit listing only to values with specific action value
* @apiParam {String} [sess] Limit listing only to values with specific session identifier
* @apiParam {String} [ip Limit listing only to values with specific IP address
* @apiParam {Number} [limit=20] How many records to return
* @apiParam {Number} [page=1] Current page number. Informational only, page numbers start from 1
* @apiParam {Number} [next] Cursor value for next page, retrieved from <code>nextCursor</code> response value
* @apiParam {Number} [previous] Cursor value for previous page, retrieved from <code>previousCursor</code> response value
*
* @apiSuccess {Boolean} success Indicates successful response
* @apiSuccess {Number} total How many results were found
* @apiSuccess {Number} page Current page number. Derived from <code>page</code> query argument
* @apiSuccess {String} previousCursor Either a cursor string or false if there are not any previous results
* @apiSuccess {String} nextCursor Either a cursor string or false if there are not any next results
* @apiSuccess {Object[]} results Event listing
* @apiSuccess {String} results.id ID of the Event
* @apiSuccess {String} results.action Action identifier
* @apiSuccess {String} results.result Did the action succeed
* @apiSuccess {String} results.sess Session identifier
* @apiSuccess {String} results.ip IP address of the Event
* @apiSuccess {String} results.created Datestring of the Event time
*
* @apiError error Description of the error
*
* @apiExample {curl} Example usage:
* curl -i "http://localhost:8080/users/59fc66a03e54454869460e45/authlog?action=account+created"
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "success": true,
* "action": "account created",
* "total": 1,
* "page": 1,
* "previousCursor": false,
* "nextCursor": false,
* "results": [
* {
* "id": "59fc66a03e54454869460e4d",
* "action": "account created",
* "result": "success",
* "sess": null,
* "ip": null,
* "created": "2017-11-03T12:52:48.792Z",
* "expires": "2017-12-03T12:52:48.792Z"
* }
* ]
* }
*
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 200 OK
* {
* "error": "Database error"
* }
*/
server.get({ name: 'authlog', path: '/users/:user/authlog' }, (req, res, next) => {
res.charSet('utf-8');

8
lib/user-handler.js
View file

@ -271,6 +271,14 @@ class UserHandler {
if (enabled2fa.length) {
meta.require2fa = enabled2fa.length ? enabled2fa.join(',') : false;
}
if (requiredScope !== 'master' && enabled2fa.length) {
// master password can not be used for other stuff if 2FA is enabled
meta.result = 'fail';
meta.source = 'master';
return this.logAuthEvent(userData._id, meta, () => authFail(new Error('Authentication failed. Invalid scope')));
}
return this.logAuthEvent(userData._id, meta, () => {
let authResponse = {
user: userData._id,