Continue api-reference docs

backend/src/app.ts

@@ -8,7 +8,7 @@ import cookieParser from 'cookie-parser';
 import dotenv from 'dotenv';
 import swaggerUi = require('swagger-ui-express');
 // eslint-disable-next-line @typescript-eslint/no-var-requires
-const swaggerFile = require('../api-documentation.json')
+const swaggerFile = require('../spec.json')
 
 
 dotenv.config();
@@ -41,7 +41,8 @@ import {
   integrationAuth as v1IntegrationAuthRouter
 } from './routes/v1';
 import {
-  secret as v2SecretRouter,
+  users as v2UsersRouter,
+  secret as v2SecretRouter, // begin to phase out
   secrets as v2SecretsRouter,
   workspace as v2WorkspaceRouter,
   serviceTokenData as v2ServiceTokenDataRouter,
@@ -103,6 +104,7 @@ app.use('/api/v1/integration', v1IntegrationRouter);
 app.use('/api/v1/integration-auth', v1IntegrationAuthRouter);
 
 // v2 routes
+app.use('/api/v2/users', v2UsersRouter);
 app.use('/api/v2/workspace', v2WorkspaceRouter); // TODO: turn into plural route
 app.use('/api/v2/secret', v2SecretRouter); // stop supporting, TODO: revise
 app.use('/api/v2/secrets', v2SecretsRouter);

backend/src/controllers/v1/authController.ts

@@ -170,10 +170,11 @@ export const logout = async (req: Request, res: Response) => {
  * @param res
  * @returns
  */
-export const checkAuth = async (req: Request, res: Response) =>
-  res.status(200).send({
+export const checkAuth = async (req: Request, res: Response) => {
+  return res.status(200).send({
     message: 'Authenticated'
   });
+}
 
 /**
  * Return new token by redeeming refresh token

backend/src/controllers/v2/index.ts

@@ -1,3 +1,4 @@
+import * as usersController from './usersController';
 import * as workspaceController from './workspaceController';
 import * as serviceTokenDataController from './serviceTokenDataController';
 import * as apiKeyDataController from './apiKeyDataController';
@@ -5,6 +6,7 @@ import * as secretController from './secretController';
 import * as secretsController from './secretsController';
 
 export {
+    usersController,
     workspaceController,
     serviceTokenDataController,
     apiKeyDataController,

backend/src/controllers/v2/secretsController.ts

@@ -21,6 +21,53 @@ import { BadRequestError } from '../../utils/errors';
  * @param res 
  */
 export const createSecrets = async (req: Request, res: Response) => {
+    /* 
+    #swagger.summary = 'Create new secret(s)'
+    #swagger.description = 'Create one or many secrets for a given project and environment.'
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+    #swagger.requestBody = {
+      "required": true,
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+                "workspaceId": {
+                    "type": "string",
+                    "description": "ID of project",
+                },
+                "environment": {
+                    "type": "string",
+                    "description": "Environment within project"
+                },
+                "secrets": {
+                    $ref: "#/components/schemas/CreateSecret",
+                    "description": "Secret(s) to create - object or array of objects"
+                }
+            }
+          }
+        }
+      }
+    }
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                "schema": { 
+                    "type": "array",
+                    "items": {
+                        $ref: "#/components/schemas/Secret" 
+                    },
+                    "description": "Array of newly-created secrets for the given project and environment"
+                }
+            }           
+        }
+    }   
+    */
     const channel = req.headers?.['user-agent']?.toLowerCase().includes('mozilla') ? 'web' : 'cli'; 
     const { workspaceId, environment } = req.body;
     
@@ -150,6 +197,49 @@ export const createSecrets = async (req: Request, res: Response) => {
  * @returns 
  */
 export const getSecrets = async (req: Request, res: Response) => {
+    /* 
+    #swagger.summary = 'Read secrets'
+    #swagger.description = 'Read secrets from a project and environment'
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+    #swagger.requestBody = {
+      "required": true,
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+                "workspaceId": {
+                    "type": "string",
+                    "description": "ID of project"
+                },
+                "environment": {
+                    "type": "string",
+                    "description": "Environment within project"
+                }
+            }
+          }
+        }
+      }
+    }
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                "schema": { 
+                    "type": "array",
+                    "items": {
+                        $ref: "#/components/schemas/Secret" 
+                    },
+                    "description": "Array of secrets for the given project and environment"
+                }
+            }           
+        }
+    }   
+    */
     const { workspaceId, environment } = req.query;
     
     let userId: Types.ObjectId | undefined = undefined // used for getting personal secrets for user
@@ -217,6 +307,48 @@ export const getSecrets = async (req: Request, res: Response) => {
  * @param res 
  */
 export const updateSecrets = async (req: Request, res: Response) => {
+    
+    // TODO: fix update secret schema
+    
+    /* 
+    #swagger.summary = 'Update secret(s)'
+    #swagger.description = 'Update secret(s)'
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+    #swagger.requestBody = {
+      "required": true,
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+                "secrets": {
+                    $ref: "#/components/schemas/UpdateSecret",
+                    "description": "Secret(s) to update - object or array of objects"
+                }
+            }
+          }
+        }
+      }
+    }
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                "schema": { 
+                    "type": "array",
+                    "items": {
+                        $ref: "#/components/schemas/Secret" 
+                    },
+                    "description": "Array of newly-updated secrets for the given project and environment"
+                }
+            }           
+        }
+    }   
+    */
     const channel = req.headers?.['user-agent']?.toLowerCase().includes('mozilla') ? 'web' : 'cli'; 
     
     // TODO: move type
@@ -384,6 +516,45 @@ export const updateSecrets = async (req: Request, res: Response) => {
  * @param res 
  */
 export const deleteSecrets = async (req: Request, res: Response) => {
+    /* 
+    #swagger.summary = 'Delete secret(s)'
+    #swagger.description = 'Delete one or many secrets by their ID(s)'
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+    #swagger.requestBody = {
+      "required": true,
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+                "secretIds": {
+                    "type": "string",
+                    "description": "ID(s) of secrets - string or array of strings"
+                },
+            }
+          }
+        }
+      }
+    }
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                schema: { 
+                    "type": "array",
+                    "items": {
+                        $ref: "#/components/schemas/Secret" 
+                    },
+                    "description": "Array of deleted secrets"
+                }
+            }           
+        }
+    }   
+    */
     const channel = req.headers?.['user-agent']?.toLowerCase().includes('mozilla') ? 'web' : 'cli'; 
     const toDelete = req.secrets.map((s: any) => s._id);
     

backend/src/controllers/v2/usersController.ts

@@ -0,0 +1,44 @@
+import { Request, Response } from 'express';
+import * as Sentry from '@sentry/node';
+import {
+    User
+} from '../../models';
+
+export const getMe = async (req: Request, res: Response) => {
+    /* 
+    #swagger.summary = "Retrieve the current user on the request"
+    #swagger.description = "Retrieve the current user on the request"
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                "schema": { 
+                    "type": "object",
+                    $ref: "#/components/schemas/CurrentUser",
+                    "description": "Current user on request"
+                }
+            }           
+        }
+    }   
+    */
+    let user;
+    try {
+        user = await User
+            .findById(req.user._id)
+            .select('+publicKey +encryptedPrivateKey');
+    } catch (err) {
+        Sentry.setUser({ email: req.user.email });
+		Sentry.captureException(err);
+		return res.status(400).send({
+			message: 'Failed to get user'
+		});
+    }
+    
+    return res.status(200).send({
+        user
+    });
+}

backend/src/controllers/v2/workspaceController.ts

@@ -169,6 +169,34 @@ export const pullSecrets = async (req: Request, res: Response) => {
 };
 
 export const getWorkspaceKey = async (req: Request, res: Response) => {
+	/* 
+    #swagger.summary = 'Return encrypted project key'
+    #swagger.description = 'Return encrypted project key'
+    
+    #swagger.security = [{
+        "apiKeyAuth": []
+    }]
+
+	#swagger.parameters['workspaceId'] = {
+		"description": "ID of project",
+		"required": true,
+		"type": "string"
+	} 
+
+    #swagger.responses[200] = {
+        content: {
+            "application/json": {
+                "schema": { 
+                    "type": "array",
+                    "items": {
+                        $ref: "#/components/schemas/ProjectKey" 
+                    },
+                    "description": "Encrypted project key for the given project"
+                }
+            }           
+        }
+    }   
+    */
 	let key;
 	try {
 		const { workspaceId } = req.params;

backend/src/routes/v2/index.ts

@@ -1,3 +1,4 @@
+import users from './users';
 import secret from './secret'; // stop-supporting
 import secrets from './secrets';
 import workspace from './workspace';
@@ -5,6 +6,7 @@ import serviceTokenData from './serviceTokenData';
 import apiKeyData from './apiKeyData';
 
 export {
+    users,
     secret,
     secrets,
     workspace,

backend/src/routes/v2/users.ts

@@ -0,0 +1,16 @@
+import express from 'express';
+const router = express.Router();
+import {
+    requireAuth
+} from '../../middleware';
+import { usersController } from '../../controllers/v2';
+
+router.get(
+    '/me',
+    requireAuth({
+        acceptedAuthModes: ['jwt']
+    }),
+    usersController.getMe
+);
+
+export default router;