feature: refactor API to use authentication and assertions

packages/app/auth/user.ts

@@ -6,8 +6,10 @@ import { authOptions } from 'pages/api/auth/[...nextauth]'
 import { getServerSession } from 'next-auth'
 import { UserWithRoles } from './types'
 
-export async function getLoggedInUser(req: any, res: any): Promise<UserWithRoles> {
-    // TODO: figure out correct typings
+export async function getLoggedInUser(
+    req: any,
+    res: any
+): Promise<UserWithRoles | undefined> {
     const session = await getServerSession(req, res, authOptions)
 
     if (!session?.user?.uid) {

packages/app/declarations.d.ts

@@ -1,9 +1,9 @@
+import { DetailedHTMLProps, HTMLAttributes } from 'react'
+import { HttpError } from 'http-errors'
 import { JSX as LocalJSX } from '@gesdisc/meditor-components/loader'
+import 'next-auth'
 import type { CKEditor } from 'ckeditor4-react'
-import { DetailedHTMLProps, HTMLAttributes } from 'react'
-import type { HttpException } from './utils/errors'
 import type { Stan } from 'node-nats-streaming'
-import 'next-auth'
 import type { User as NextAuthUser } from 'next-auth'
 
 // Read more at: https://next-auth.js.org/getting-started/typescript#module-augmentation
@@ -30,7 +30,7 @@ export type APIError = {
     error: string
 }
 
-export type ErrorData<T> = [Error | HttpException | null, T | null]
+export type ErrorData<T> = [Error | HttpError | null, T | null]
 
 type gReactProps<T> = {
     [P in keyof T]?: DetailedHTMLProps<HTMLAttributes<T[P]>, T[P]>

packages/app/lib/with-api-error-handler.ts

@@ -0,0 +1,65 @@
+import { NextApiRequest, NextApiResponse } from 'next'
+import { ZodError } from 'zod'
+import createError from 'http-errors'
+import { parameterWithInflection } from './grammar'
+import log from './log'
+
+export function withApiErrorHandler(handler) {
+    return async (req: NextApiRequest, res: NextApiResponse) => {
+        try {
+            // Call the original handler
+            await handler(req, res)
+        } catch (err) {
+            // Any unhandled exceptions will be caught and reported as a clean JSON response
+            return apiError(err, res)
+        }
+    }
+}
+
+/**
+ * converts errors to a JSON api response
+ * To prevent leaking implementation details to an end-user, if the error isn't an instance of HttpError, only return a generic error.
+ */
+export function apiError(
+    error: Error | ZodError | createError.HttpError,
+    response: NextApiResponse
+) {
+    let interstitialError = error
+
+    if (error.name === 'ZodError') {
+        interstitialError = formatZodError(error as ZodError)
+    }
+
+    const safeError =
+        interstitialError instanceof createError.HttpError
+            ? interstitialError
+            : new createError.InternalServerError()
+
+    if (safeError instanceof createError.InternalServerError) {
+        // this is an unknown error, lets dump out the details so we can debug it later
+        log.error(safeError)
+    }
+
+    return response.status(safeError.status).json({
+        status: safeError.status,
+        error: safeError.message,
+    })
+}
+
+export function formatZodError(error: ZodError, messagePrefix?: string) {
+    const errorString = error.issues.reduce((accumulator, current, index, self) => {
+        //* We want spaces between errors but not for the last error.
+        const maybeSpace = index + 1 === self.length ? '' : ' '
+
+        accumulator += `${
+            messagePrefix ??
+            `For query ${parameterWithInflection(
+                current.path.length
+            )} ${current.path.toString()}: `
+        }${current.message}.${maybeSpace}`
+
+        return accumulator
+    }, ``)
+
+    return new createError.BadRequest(errorString)
+}

packages/app/middleware.ts

@@ -0,0 +1,16 @@
+export { default } from 'next-auth/middleware'
+
+export const config = {
+    matcher: [
+        /*
+         * Require authentication for all request paths except for the ones starting with:
+         * - installation
+         * - signin (mEditor's sign in page)
+         * - api (API routes)
+         * - _next (NextJS static files)
+         * - images (/public/images static images)
+         * - favicon.ico
+         */
+        '/((?!installation|signin|api|_next|images|favicon.ico).*)',
+    ],
+}

packages/app/models/service.ts

@@ -1,12 +1,12 @@
 import jsonpath from 'jsonpath'
-import type { ErrorData } from '../declarations'
-import { getDocumentsDb } from '../documents/db'
 import log from '../lib/log'
-import { runModelTemplates } from '../macros/service'
 import { ErrorCode, HttpException } from '../utils/errors'
-import { isJson } from '../utils/jsonschema-validate'
-import { getWorkflowByDocumentState } from '../workflows/service'
+import { getDocumentsDb } from '../documents/db'
 import { getModelsDb } from './db'
+import { getWorkflowByDocumentState } from '../workflows/service'
+import { isJson } from '../utils/jsonschema-validate'
+import { runModelTemplates } from '../macros/service'
+import type { ErrorData } from '../declarations'
 import type { Model, ModelWithWorkflow } from './types'
 import type { UserWithRoles } from 'auth/types'
 
@@ -203,7 +203,8 @@ export async function getModelsWithDocumentCount(): Promise<ErrorData<Model[]>>
 
 /**
  * if user is not authenticated, verify the requested model is not in the list of models requiring authentication
+ * this was a mEditor design decision early on to allow anonymous access to most documents
  */
-export function userCanAccessModel(modelName: string, user: UserWithRoles) {
-    return !!user?.uid || !MODELS_REQUIRING_AUTHENTICATION.includes(modelName)
+export async function userCanAccessModel(user: UserWithRoles, modelName: string) {
+    return user?.uid ? true : !MODELS_REQUIRING_AUTHENTICATION.includes(modelName)
 }

packages/app/package.json

@@ -30,6 +30,7 @@
         "eslint-config-next": "^15.0.3",
         "fuse.js": "^6.6.2",
         "he": "^1.2.0",
+        "http-errors": "^2.0.0",
         "immer": "^9.0.6",
         "immutable-json-patch": "^6.0.1",
         "isomorphic-unfetch": "^3.0.0",

packages/app/pages/api/admin/index.ts

@@ -1,8 +1,9 @@
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
 import type { NextApiRequest, NextApiResponse } from 'next'
+import createError from 'http-errors'
 
-export default async function handler(_req: NextApiRequest, res: NextApiResponse) {
-    // TODO: implement
-    res.status(501).json({
-        message: 'Not Implemented',
-    })
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
+    throw createError.NotImplemented()
 }
+
+export default withApiErrorHandler(handler)

packages/app/pages/api/admin/seed-db/index.ts

@@ -1,20 +1,19 @@
 import type { NextApiRequest, NextApiResponse } from 'next'
 import { setUpNewInstallation } from '../../../../setup/service'
-import { apiError } from '../../../../utils/errors'
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
+import assert from 'assert'
+import createError from 'http-errors'
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-    switch (req.method) {
-        case 'POST': {
-            const [error] = await setUpNewInstallation(req.body)
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
+    assert(req.method === 'POST', new createError.MethodNotAllowed())
 
-            if (!!error) {
-                return apiError(error, res)
-            }
+    const [error] = await setUpNewInstallation(req.body)
 
-            return res.status(204).end()
-        }
-
-        default:
-            return res.status(405).end()
+    if (!!error) {
+        throw error
     }
+
+    return res.status(204).end()
 }
+
+export default withApiErrorHandler(handler)

packages/app/pages/api/health/index.ts

@@ -1,3 +1,4 @@
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
 import type { NextApiRequest, NextApiResponse } from 'next'
 
 const healthcheck = {
@@ -8,7 +9,7 @@ const healthcheck = {
     },
 }
 
-export default async function handler(_req: NextApiRequest, res: NextApiResponse) {
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
     //timeout for fetch request sice meditor_notifier is an internal service
     const controller = new AbortController()
 
@@ -33,3 +34,5 @@ export default async function handler(_req: NextApiRequest, res: NextApiResponse
         res.status(500).json({ message: 'Meditor API is not healthy', err })
     }
 }
+
+export default withApiErrorHandler(handler)

packages/app/pages/api/legacy-endpoints/changeDocumentState.ts

@@ -1,8 +1,8 @@
 import type { NextApiRequest, NextApiResponse } from 'next'
-import { apiError } from 'utils/errors'
 import changeDocumentStateHandler from '../models/[modelName]/documents/[documentTitle]/change-document-state'
 import { baseDocumentSchema } from './_schemas'
 import { z } from 'zod'
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
 
 const schema = baseDocumentSchema
     .extend({
@@ -14,14 +14,12 @@ const schema = baseDocumentSchema
         state,
     }))
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-    try {
-        // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
-        req.query = schema.parse(req.query)
-        req.method = req.method === 'GET' ? 'POST' : req.method // old API used GET, new API uses POST
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
+    // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
+    req.query = schema.parse(req.query)
+    req.method = req.method === 'GET' ? 'POST' : req.method // old API used GET, new API uses POST
 
-        return changeDocumentStateHandler(req, res)
-    } catch (err) {
-        return apiError(err, res)
-    }
+    return changeDocumentStateHandler(req, res)
 }
+
+export default withApiErrorHandler(handler)

packages/app/pages/api/legacy-endpoints/cloneDocument.ts

@@ -1,8 +1,8 @@
 import type { NextApiRequest, NextApiResponse } from 'next'
-import { apiError } from 'utils/errors'
 import cloneDocumentHandler from '../models/[modelName]/documents/[documentTitle]/clone-document'
 import { baseDocumentSchema } from './_schemas'
 import { z } from 'zod'
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
 
 const schema = baseDocumentSchema
     .extend({
@@ -14,13 +14,11 @@ const schema = baseDocumentSchema
         newTitle,
     }))
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-    try {
-        // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
-        req.query = schema.parse(req.query)
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
+    // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
+    req.query = schema.parse(req.query)
 
-        return cloneDocumentHandler(req, res)
-    } catch (err) {
-        return apiError(err, res)
-    }
+    return cloneDocumentHandler(req, res)
 }
+
+export default withApiErrorHandler(handler)

packages/app/pages/api/legacy-endpoints/getComments.ts

@@ -1,15 +1,13 @@
 import type { NextApiRequest, NextApiResponse } from 'next'
-import { apiError } from 'utils/errors'
 import getCommentsHandler from '../models/[modelName]/documents/[documentTitle]/comments/'
 import { documentSchema } from './_schemas'
+import { withApiErrorHandler } from 'lib/with-api-error-handler'
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-    try {
-        // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
-        req.query = documentSchema.parse(req.query)
+const handler = async (req: NextApiRequest, res: NextApiResponse) => {
+    // replaces query params with params mapped to RESTful names (e.g. "model" -> "modelName", etc.)
+    req.query = documentSchema.parse(req.query)
 
-        return getCommentsHandler(req, res)
-    } catch (err) {
-        return apiError(err, res)
-    }
+    return getCommentsHandler(req, res)
 }
+
+export default withApiErrorHandler(handler)