emailengine-app 2.68.1 → 2.70.0

package/lib/api-routes/template-routes.js

@@ -4,11 +4,14 @@ const { redis } = require('../db');
 const { Account } = require('../account');
 const getSecret = require('../get-secret');
 const { templates } = require('../templates');
-const Boom = require('@hapi/boom');
 const Joi = require('joi');
 const { failAction } = require('../tools');
+const { handleError, throwNotFound } = require('./route-helpers');
 
-const { templateSchemas, accountIdSchema } = require('../schemas');
+const { templateSchemas, accountIdSchema, errorResponses } = require('../schemas');
+
+// Template owner field shared by all template response schemas
+const templateAccountIdSchema = accountIdSchema.required().allow(null).description('Account ID. Null for public templates');
 
 async function init(args) {
     const { server, call, CORS_CONFIG } = args;
@@ -43,15 +46,7 @@ async function init(args) {
                     request.payload.content
                 );
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
 
@@ -60,7 +55,11 @@ async function init(args) {
             notes: 'Create a new stored template. Templates can be used when sending emails as the content of the message.',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -112,7 +111,7 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     created: Joi.boolean().description('Was the template created or not'),
-                    account: accountIdSchema.required(),
+                    account: templateAccountIdSchema,
                     id: Joi.string().max(256).required().example('example').description('Template ID')
                 }).label('CreateTemplateResponse'),
                 failAction: 'log'
@@ -135,15 +134,7 @@ async function init(args) {
 
                 return await templates.update(request.params.template, meta, request.payload.content);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
 
@@ -152,7 +143,11 @@ async function init(args) {
             notes: 'Update a stored template.',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -198,7 +193,7 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     updated: Joi.boolean().description('Was the template updated or not'),
-                    account: accountIdSchema.required(),
+                    account: templateAccountIdSchema,
                     id: Joi.string().max(256).required().example('example').description('Template ID')
                 }).label('UpdateTemplateResponse'),
                 failAction: 'log'
@@ -220,15 +215,7 @@ async function init(args) {
 
                 return await templates.list(request.query.account, request.query.page, request.query.pageSize);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
 
@@ -237,7 +224,11 @@ async function init(args) {
             notes: 'Lists stored templates for the account',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -270,7 +261,7 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    account: accountIdSchema.required(),
+                    account: templateAccountIdSchema,
                     total: Joi.number().integer().example(120).description('How many matching entries').label('TotalNumber'),
                     page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
                     pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
@@ -308,17 +299,13 @@ async function init(args) {
 
         async handler(request) {
             try {
-                return await templates.get(request.params.template);
-            } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
+                let templateData = await templates.get(request.params.template);
+                if (!templateData) {
+                    throwNotFound();
                 }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                return templateData;
+            } catch (err) {
+                handleError(request, err);
             }
         },
 
@@ -327,7 +314,11 @@ async function init(args) {
             notes: 'Retrieve template content and information',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -349,7 +340,7 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    account: accountIdSchema.required(),
+                    account: templateAccountIdSchema,
                     id: Joi.string().max(256).required().example('AAABgS-UcAYAAAABAA').description('Template ID'),
                     name: Joi.string().max(256).example('Transaction receipt').description('Name of the template').label('TemplateName').required(),
                     description: Joi.string()
@@ -369,12 +360,7 @@ async function init(args) {
                         subject: templateSchemas.subject,
                         text: templateSchemas.text,
                         html: templateSchemas.html,
-                        previewText: templateSchemas.previewText,
-                        format: Joi.string()
-                            .valid('html', 'markdown')
-                            .default('html')
-                            .description('Markup language for HTML ("html" or "markdown")')
-                            .label('TemplateContentFormat')
+                        previewText: templateSchemas.previewText
                     }).label('RequestTemplateContent')
                 }).label('AccountTemplateResponse'),
                 failAction: 'log'
@@ -390,15 +376,7 @@ async function init(args) {
             try {
                 return await templates.del(request.params.template);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -406,7 +384,11 @@ async function init(args) {
             notes: 'Delete a stored template',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -430,7 +412,7 @@ async function init(args) {
             response: {
                 schema: Joi.object({
                     deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the template deleted'),
-                    account: accountIdSchema.required(),
+                    account: templateAccountIdSchema,
                     id: Joi.string().max(256).required().example('AAABgS-UcAYAAAABAA').description('Template ID')
                 }).label('DeleteTemplateResponse'),
                 failAction: 'log'
@@ -446,20 +428,19 @@ async function init(args) {
             let accountObject = new Account({ redis, account: request.params.account, call, secret: await getSecret() });
 
             try {
+                if (!request.query.force) {
+                    let err = new Error('Set the force=true query parameter to flush account templates');
+                    err.code = 'ForceRequired';
+                    err.statusCode = 400;
+                    throw err;
+                }
+
                 // throws if account does not exist
                 await accountObject.loadAccountData();
 
                 return await templates.flush(request.params.account);
             } catch (err) {
-                request.logger.error({ msg: 'API request failed', err });
-                if (Boom.isBoom(err)) {
-                    throw err;
-                }
-                let error = Boom.boomify(err, { statusCode: err.statusCode || 500 });
-                if (err.code) {
-                    error.output.payload.code = err.code;
-                }
-                throw error;
+                handleError(request, err);
             }
         },
         options: {
@@ -467,7 +448,11 @@ async function init(args) {
             notes: 'Delete all stored templates for an account',
             tags: ['api', 'Templates'],
 
-            plugins: {},
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
 
             auth: {
                 strategy: 'api-token',
@@ -499,7 +484,7 @@ async function init(args) {
 
             response: {
                 schema: Joi.object({
-                    deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Were the templates flushed'),
+                    flushed: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Were the templates flushed'),
                     account: accountIdSchema.required()
                 }).label('FlushTemplatesResponse'),
                 failAction: 'log'

package/lib/api-routes/token-routes.js

@@ -0,0 +1,297 @@
+'use strict';
+
+const Joi = require('joi');
+const { redis } = require('../db');
+const { Account } = require('../account');
+const getSecret = require('../get-secret');
+const tokens = require('../tokens');
+const { failAction } = require('../tools');
+const { handleError } = require('./route-helpers');
+const { accountIdSchema, tokenRestrictionsSchema, ipSchema, tokenIdSchema, errorResponses } = require('../schemas');
+
+const tokenAccessSchema = Joi.object({
+    time: Joi.date().iso().allow(null).example('2021-02-17T13:43:18.860Z').description('Last time this token was used. Null if the token has never been used'),
+    ip: ipSchema.allow(null).description('IP address of the last request that used this token. Null if the address was not available')
+})
+    .unknown()
+    .description('Token usage information')
+    .label('TokenAccess');
+
+const tokenScopesSchema = Joi.array()
+    .items(Joi.string().example('api').label('TokenScopeEntry'))
+    .description('Scopes this token is valid for')
+    .label('TokenScopes');
+
+const tokenMetadataSchema = Joi.string()
+    .empty('')
+    .max(1024 * 1024)
+    .custom((value, helpers) => {
+        try {
+            // check if parsing fails
+            JSON.parse(value);
+            return value;
+        } catch (err) {
+            return helpers.message('Metadata must be a valid JSON string');
+        }
+    })
+    .example('{"example": "value"}')
+    .description('Related metadata in JSON format')
+    .label('JsonMetaData');
+
+// Both token listings (root and account) return the same item shape from tokens.list(),
+// the account listing just adds the account ID
+const tokenListItemFields = {
+    description: Joi.string().empty('').trim().max(1024).example('Token description').description('Token description'),
+    metadata: tokenMetadataSchema,
+    ip: ipSchema.description('IP address of the requester').label('TokenIP'),
+    remoteAddress: ipSchema.description('IP address of the client that created the token').label('TokenRemoteAddress'),
+    scopes: tokenScopesSchema,
+    restrictions: tokenRestrictionsSchema,
+    created: Joi.date().iso().example('2021-02-17T13:43:18.860Z').description('The time this token was created'),
+    access: tokenAccessSchema,
+    id: tokenIdSchema
+};
+
+async function init(args) {
+    const { server, call, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'POST',
+        path: '/v1/token',
+
+        async handler(request) {
+            let accountObject = new Account({
+                redis,
+                account: request.payload.account,
+                call,
+                secret: await getSecret(),
+                timeout: request.headers['x-ee-timeout']
+            });
+
+            try {
+                // throws if account does not exist
+                await accountObject.loadAccountData();
+
+                let token = await tokens.provision(Object.assign({}, request.payload, { remoteAddress: request.app.ip }));
+
+                return { token };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'Provision an access token',
+            notes: 'Provisions a new access token for an account',
+            tags: ['api', 'Access Tokens'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                payload: Joi.object({
+                    account: accountIdSchema.required(),
+
+                    description: Joi.string().empty('').trim().max(1024).required().example('Token description').description('Token description'),
+
+                    scopes: Joi.array()
+                        .items(Joi.string().valid('api', 'smtp', 'imap-proxy').label('TokenScope'))
+                        .single()
+                        .default(['api'])
+                        .required()
+                        .description(
+                            'Token permission scopes: "api" for REST API access, "smtp" for SMTP submission, "imap-proxy" for IMAP proxy authentication'
+                        )
+                        .label('Scopes'),
+
+                    metadata: tokenMetadataSchema,
+
+                    restrictions: tokenRestrictionsSchema,
+
+                    ip: ipSchema.description('IP address of the requester').label('TokenIP')
+                }).label('CreateToken')
+            },
+
+            response: {
+                schema: Joi.object({
+                    token: Joi.string().length(64).hex().required().example('123456').description('Access token')
+                }).label('CreateTokenResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'DELETE',
+        path: '/v1/token/{token}',
+
+        async handler(request) {
+            try {
+                return { deleted: await tokens.delete(request.params.token, { remoteAddress: request.app.ip }) };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Remove a token',
+            notes: 'Delete an access token',
+            tags: ['api', 'Access Tokens'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    token: Joi.string().length(64).hex().required().example('123456').description('Access token')
+                }).label('DeleteTokenRequest')
+            },
+
+            response: {
+                schema: Joi.object({
+                    deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the token deleted')
+                }).label('DeleteTokenRequestResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'GET',
+        path: '/v1/tokens',
+
+        async handler(request) {
+            try {
+                // TODO: allow paging
+                return { tokens: (await tokens.list(null, 0, 1000)).tokens };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List root tokens',
+            notes: 'Lists access tokens registered for root access',
+            tags: ['api', 'Access Tokens'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction
+            },
+
+            response: {
+                schema: Joi.object({
+                    tokens: Joi.array().items(Joi.object(tokenListItemFields).label('RootTokensItem')).label('RootTokensEntries')
+                }).label('RootTokensResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'GET',
+        path: '/v1/tokens/account/{account}',
+
+        async handler(request) {
+            try {
+                // TODO: allow paging
+                return { tokens: (await tokens.list(request.params.account, 0, 1000)).tokens };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List account tokens',
+            notes: 'Lists access tokens registered for an account',
+            tags: ['api', 'Access Tokens'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+                params: Joi.object({
+                    account: accountIdSchema.required()
+                })
+            },
+
+            response: {
+                schema: Joi.object({
+                    tokens: Joi.array()
+                        .items(
+                            Joi.object({
+                                account: accountIdSchema.required(),
+                                ...tokenListItemFields
+                            }).label('AccountTokensItem')
+                        )
+                        .label('AccountTokensEntries')
+                }).label('AccountsTokensResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;