@terreno/api 0.13.2 → 0.14.0

package/src/configurationApp.ts

@@ -17,7 +17,7 @@ const requireAdmin = (
   _res: express.Response,
   next: express.NextFunction
 ): void => {
-  if (!(req as any).user?.admin) {
+  if (!req.user?.admin) {
     next(new APIError({status: 403, title: "Admin access required"}));
     return;
   }
@@ -32,7 +32,7 @@ interface ConfigFieldMeta {
   required: boolean;
   description?: string;
   enum?: string[];
-  default?: any;
+  default?: unknown;
   secret?: boolean;
   widget?: string;
 }
@@ -59,6 +59,7 @@ export interface ConfigurationMetaResponse {
  */
 export interface ConfigurationAppOptions {
   /** The Mongoose model with configurationPlugin applied. */
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> required for invariance — consumers pass arbitrary configuration models
   model: Model<any>;
   /** Base path for configuration routes. Defaults to "/configuration". */
   basePath?: string;
@@ -70,8 +71,15 @@ export interface ConfigurationAppOptions {
  * Extracts field metadata from an OpenAPI properties object, augmented with
  * secret info from the Mongoose schema.
  */
+interface OpenApiPropertyMeta {
+  type?: string;
+  default?: unknown;
+  description?: string;
+  enum?: string[];
+}
+
 const extractFieldMeta = (
-  properties: Record<string, any>,
+  properties: Record<string, OpenApiPropertyMeta>,
   required: string[],
   schema: Schema,
   prefix: string,
@@ -81,7 +89,9 @@ const extractFieldMeta = (
   for (const [key, prop] of Object.entries(properties)) {
     const fullPath = prefix ? `${prefix}.${key}` : key;
     const schemaPath = schema.path(fullPath);
-    const opts = schemaPath?.options as any;
+    const opts = schemaPath?.options as
+      | {description?: string; secret?: boolean; default?: unknown}
+      | undefined;
 
     fields[key] = {
       default: prop.default,
@@ -112,17 +122,23 @@ const SECRET_REDACTED = "********";
  * Replaces values at secret paths with a placeholder string.
  */
 const redactSecrets = (
-  obj: Record<string, any>,
+  obj: Record<string, unknown>,
   secretFields: SecretFieldMeta[]
-): Record<string, any> => {
-  const redacted = {...obj};
+): Record<string, unknown> => {
+  const redacted: Record<string, unknown> = {...obj};
   for (const field of secretFields) {
     const parts = field.path.split(".");
-    let current: any = redacted;
+    let current: Record<string, unknown> | null = redacted;
     for (let i = 0; i < parts.length - 1; i++) {
-      if (current[parts[i]] != null && typeof current[parts[i]] === "object") {
-        current[parts[i]] = {...current[parts[i]]};
-        current = current[parts[i]];
+      if (!current) {
+        break;
+      }
+      const part = parts[i];
+      const nested = current[part];
+      if (nested != null && typeof nested === "object") {
+        const copy = {...(nested as Record<string, unknown>)};
+        current[part] = copy;
+        current = copy;
       } else {
         current = null;
         break;
@@ -206,8 +222,18 @@ export class ConfigurationApp implements TerrenoPlugin {
       }
     );
 
+    interface ConfigModelStatics {
+      getSecretFields?: () => SecretFieldMeta[];
+      getConfig: () => Promise<{toJSON: () => Record<string, unknown>}>;
+      updateConfig: (
+        body: Record<string, unknown>
+      ) => Promise<{toJSON: () => Record<string, unknown>}>;
+      resolveSecrets: () => Promise<Map<string, string>>;
+    }
+    const ConfigStatics = ConfigModel as unknown as ConfigModelStatics;
+
     // Discover secret fields once at registration time
-    const secretFields: SecretFieldMeta[] = (ConfigModel as any).getSecretFields?.() ?? [];
+    const secretFields: SecretFieldMeta[] = ConfigStatics.getSecretFields?.() ?? [];
 
     // GET /configuration — current values (secrets redacted)
     app.get(
@@ -215,7 +241,7 @@ export class ConfigurationApp implements TerrenoPlugin {
       authenticateMiddleware(),
       requireAdmin,
       asyncHandler(async (_req: express.Request, res: express.Response) => {
-        const config = await (ConfigModel as any).getConfig();
+        const config = await ConfigStatics.getConfig();
         const data = redactSecrets(config.toJSON(), secretFields);
         return res.json({data});
       })
@@ -229,8 +255,8 @@ export class ConfigurationApp implements TerrenoPlugin {
       asyncHandler(async (req: express.Request, res: express.Response) => {
         // Strip internal system fields that should never be updated via the API
         const {_singleton: _s, _id: _i, __v: _v, ...safeBody} = req.body;
-        const config = await (ConfigModel as any).updateConfig(safeBody);
-        logger.info(`Configuration updated by ${(req as any).user?.email ?? "unknown"}`);
+        const config = await ConfigStatics.updateConfig(safeBody);
+        logger.info(`Configuration updated by ${req.user?.email ?? "unknown"}`);
         const data = redactSecrets(config.toJSON(), secretFields);
         return res.json({data});
       })
@@ -242,13 +268,13 @@ export class ConfigurationApp implements TerrenoPlugin {
       authenticateMiddleware(),
       requireAdmin,
       asyncHandler(async (_req: express.Request, res: express.Response) => {
-        const resolved: Map<string, string> = await (ConfigModel as any).resolveSecrets();
+        const resolved: Map<string, string> = await ConfigStatics.resolveSecrets();
         if (resolved.size > 0) {
           const updates: Record<string, unknown> = {};
           for (const [path, value] of resolved) {
             updates[path] = value;
           }
-          await (ConfigModel as any).updateConfig(updates);
+          await ConfigStatics.updateConfig(updates);
           logger.info(`Refreshed ${resolved.size}/${secretFields.length} secrets`);
         }
 
@@ -269,6 +295,7 @@ export class ConfigurationApp implements TerrenoPlugin {
    * Top-level fields with subschemas become sections.
    * Top-level scalar fields go into a "General" section.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> required for invariance with consumer-supplied configuration models
   private buildMetadata(_model: Model<any>, schema: Schema): ConfigurationMetaResponse {
     const sections: ConfigSectionMeta[] = [];
     const generalFields: Record<string, ConfigFieldMeta> = {};
@@ -279,21 +306,21 @@ export class ConfigurationApp implements TerrenoPlugin {
         return;
       }
 
-      const subSchema = (schemaType as any).schema as Schema | undefined;
+      const subSchema = (schemaType as unknown as {schema?: Schema}).schema;
 
       if (subSchema) {
         // This is a nested subschema — make it a section
         const {properties, required} = getOpenApiSpecForModel({
           modelName: pathName,
           schema: subSchema,
-        } as any);
+        } as unknown as Model<unknown>);
 
         // Filter out system fields from the subschema too
-        const filteredProperties: Record<string, any> = {};
+        const filteredProperties: Record<string, OpenApiPropertyMeta> = {};
         const filteredRequired: string[] = [];
         for (const [key, val] of Object.entries(properties)) {
           if (!SYSTEM_FIELDS.has(key)) {
-            filteredProperties[key] = val;
+            filteredProperties[key] = val as OpenApiPropertyMeta;
             if (required.includes(key)) {
               filteredRequired.push(key);
             }
@@ -309,7 +336,7 @@ export class ConfigurationApp implements TerrenoPlugin {
         );
 
         // Get description from the parent path options
-        const opts = schemaType.options as any;
+        const opts = schemaType.options as {description?: string} | undefined;
 
         sections.push({
           description: opts?.description,
@@ -319,7 +346,15 @@ export class ConfigurationApp implements TerrenoPlugin {
         });
       } else {
         // Scalar top-level field — goes into "General" section
-        const opts = schemaType.options as any;
+        const opts = schemaType.options as
+          | {
+              default?: unknown;
+              description?: string;
+              enum?: string[];
+              required?: boolean;
+              secret?: boolean;
+            }
+          | undefined;
         const fullPath = pathName;
 
         generalFields[pathName] = {
@@ -349,7 +384,7 @@ export class ConfigurationApp implements TerrenoPlugin {
     return {sections};
   }
 
-  private mongooseTypeToString(schemaType: any): string {
+  private mongooseTypeToString(schemaType: {instance?: string}): string {
     const instance = schemaType.instance?.toLowerCase();
     if (instance === "objectid") {
       return "string";

package/src/configurationPlugin.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {afterAll, beforeAll, beforeEach, describe, expect, it} from "bun:test";
 import mongoose, {model, Schema} from "mongoose";
 import type {SecretProvider} from "./configurationPlugin";

package/src/consentApp.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {afterEach, beforeEach, describe, expect, it} from "bun:test";
 import type express from "express";
 import supertest from "supertest";

package/src/envConfigurationPlugin.test.ts

@@ -0,0 +1,143 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test model typing
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import mongoose, {Schema} from "mongoose";
+
+import {Config} from "./config";
+import {envConfigurationPlugin} from "./envConfigurationPlugin";
+
+interface EnvDocShape {
+  env: Map<string, string>;
+}
+
+const testSchema = new Schema<EnvDocShape>({}, {strict: "throw"});
+testSchema.plugin(envConfigurationPlugin);
+
+const TestEnvConfig =
+  (mongoose.models.TestEnvConfig as mongoose.Model<EnvDocShape>) ??
+  mongoose.model<EnvDocShape>("TestEnvConfig", testSchema);
+
+const setupLoader = (): void => {
+  Config.setEnvLoader(async () => {
+    const doc = (await TestEnvConfig.findOne({}).lean()) as {
+      env?: Map<string, string> | Record<string, string>;
+    } | null;
+    if (!doc?.env) {
+      return {};
+    }
+    if (doc.env instanceof Map) {
+      const out: Record<string, string> = {};
+      for (const [k, v] of doc.env) {
+        out[k] = v;
+      }
+      return out;
+    }
+    return {...doc.env};
+  });
+};
+
+describe("envConfigurationPlugin", () => {
+  beforeEach(async () => {
+    Config.clearRegistryForTesting();
+    Config.clearOverrides();
+    Config.setCachedEnv(null);
+    Config.setEnvLoader(null);
+    Reflect.deleteProperty(process.env, "TERRENO_PLUGIN_KEY");
+
+    Config.register("TERRENO_PLUGIN_KEY", {default: "fallback"});
+
+    await mongoose.connection.db?.collection("testenvconfigs").deleteMany({});
+    setupLoader();
+  });
+
+  afterEach(async () => {
+    Config.clearRegistryForTesting();
+    Config.clearOverrides();
+    Config.setCachedEnv(null);
+    Config.setEnvLoader(null);
+    Reflect.deleteProperty(process.env, "TERRENO_PLUGIN_KEY");
+    await mongoose.connection.db?.collection("testenvconfigs").deleteMany({});
+  });
+
+  it("adds an env Map field to the schema", () => {
+    const doc = new TestEnvConfig();
+    expect(doc.env).toBeInstanceOf(Map);
+  });
+
+  it("Config.refresh() loads values from the document", async () => {
+    const doc = new TestEnvConfig();
+    doc.env.set("TERRENO_PLUGIN_KEY", "fromDoc");
+    await doc.save();
+
+    Config.setCachedEnv(null);
+    await Config.refresh();
+
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("fromDoc");
+  });
+
+  it("post-save hook refreshes the cache automatically", async () => {
+    const doc = new TestEnvConfig();
+    doc.env.set("TERRENO_PLUGIN_KEY", "first");
+    await doc.save();
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("first");
+
+    doc.env.set("TERRENO_PLUGIN_KEY", "second");
+    await doc.save();
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("second");
+  });
+
+  it("post-findOneAndUpdate hook refreshes the cache", async () => {
+    const doc = new TestEnvConfig();
+    doc.env.set("TERRENO_PLUGIN_KEY", "initial");
+    await doc.save();
+
+    await TestEnvConfig.findOneAndUpdate(
+      {_id: doc._id},
+      {env: new Map([["TERRENO_PLUGIN_KEY", "updated"]])}
+    );
+
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("updated");
+  });
+
+  it("post-updateOne hook refreshes the cache", async () => {
+    const doc = new TestEnvConfig();
+    doc.env.set("TERRENO_PLUGIN_KEY", "initial");
+    await doc.save();
+
+    await TestEnvConfig.updateOne(
+      {_id: doc._id},
+      {env: new Map([["TERRENO_PLUGIN_KEY", "updatedViaUpdateOne"]])}
+    );
+
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("updatedViaUpdateOne");
+  });
+
+  it("empty-string env values fall through to process.env", async () => {
+    process.env.TERRENO_PLUGIN_KEY = "fromEnv";
+    const doc = new TestEnvConfig();
+    doc.env.set("TERRENO_PLUGIN_KEY", "");
+    await doc.save();
+
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("fromEnv");
+  });
+
+  it("missing document yields registered defaults", async () => {
+    await Config.refresh();
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("fallback");
+  });
+
+  it("refreshFromDoc handles null document via Mongoose hook when collection is empty", async () => {
+    // Ensure collection is empty — no documents to find
+    await mongoose.connection.db?.collection("testenvconfigs").deleteMany({});
+
+    // Override the cache so we can verify it gets cleared by the hook
+    Config.setCachedEnv({TERRENO_PLUGIN_KEY: "stale"});
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("stale");
+
+    // Trigger findOneAndUpdate hook on a non-existent doc — refreshFromDoc
+    // calls findOneOrNone which returns null, so mapToObject(undefined) runs
+    await TestEnvConfig.findOneAndUpdate({_id: new mongoose.Types.ObjectId()}, {$set: {__v: 1}});
+
+    // mapToObject(undefined) returns {}, so Config falls back to the registered default
+    expect(Config.get("TERRENO_PLUGIN_KEY")).toBe("fallback");
+  });
+});

package/src/envConfigurationPlugin.ts

@@ -0,0 +1,100 @@
+import type {Document, Model, Schema} from "mongoose";
+
+import {Config} from "./config";
+import {logger} from "./logger";
+import {findOneOrNoneFor} from "./plugins";
+
+/**
+ * Adds an admin-editable `env: Map<string, string>` field to a Mongoose schema
+ * and keeps the global `Config` cache in sync with it.
+ *
+ * Companion to `Config` (config.ts). Apply alongside `configurationPlugin`
+ * when you want a singleton configuration document whose `env` map backs the
+ * runtime Config registry:
+ *
+ * ```typescript
+ * const schema = new Schema({...});
+ * schema.plugin(configurationPlugin);
+ * schema.plugin(envConfigurationPlugin);
+ *
+ * export const EnvConfig = mongoose.model("EnvConfig", schema);
+ * ```
+ *
+ * Apps still call `Config.setEnvLoader(...)` once at startup to wire the
+ * model into `Config.refresh()` — typically:
+ *
+ * ```typescript
+ * import {findOneOrNoneFor} from "@terreno/api";
+ *
+ * Config.setEnvLoader(async () => {
+ *   const doc = await findOneOrNoneFor(EnvConfig, {});
+ *   return doc?.env ? Object.fromEntries(doc.env) : {};
+ * });
+ * await Config.refresh();
+ * ```
+ *
+ * After that, the post-save / post-update hooks installed here keep the
+ * cache fresh whenever the document changes, so callers reading
+ * `Config.get("KEY")` see admin edits immediately.
+ */
+
+interface EnvDoc extends Document {
+  env?: Map<string, string> | Record<string, string>;
+}
+
+const mapToObject = (
+  env: Map<string, string> | Record<string, string> | undefined
+): Record<string, string> => {
+  if (!env) {
+    return {};
+  }
+  if (env instanceof Map) {
+    const out: Record<string, string> = {};
+    for (const [k, v] of env) {
+      out[k] = v;
+    }
+    return out;
+  }
+  return {...env};
+};
+
+const refreshFromDoc = async (Model: Model<unknown>): Promise<void> => {
+  try {
+    // biome-ignore lint/suspicious/noExplicitAny: doc shape determined by consumer schema
+    const doc = (await findOneOrNoneFor(Model as Model<any>, {})) as
+      | (Document & {env?: Map<string, string> | Record<string, string>})
+      | null;
+    Config.setCachedEnv(mapToObject(doc?.env));
+  } catch (error) {
+    logger.warn(
+      `envConfigurationPlugin: failed to refresh Config cache: ${(error as Error).message}`
+    );
+  }
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: Schema generics must be loose to accept arbitrary consumer schemas
+export const envConfigurationPlugin = (schema: Schema<any, any, any, any>): void => {
+  schema.add({
+    env: {
+      default: () => new Map<string, string>(),
+      description:
+        "Admin-editable overrides for runtime configuration. Keys are env-var names " +
+        "(e.g. EXPO_ACCESS_TOKEN) and values are stored as strings. Overrides win " +
+        "over process.env at read time via the Config registry.",
+      of: String,
+      type: Map,
+    },
+  });
+
+  schema.post("save", async function (this: EnvDoc) {
+    await refreshFromDoc(this.constructor as Model<unknown>);
+  });
+
+  schema.post("findOneAndUpdate", async function (this: {model: Model<unknown>}) {
+    await refreshFromDoc(this.model);
+  });
+
+  schema.post("updateOne", async function (this: {model: Model<unknown>}) {
+    await refreshFromDoc(this.model);
+  });
+};

package/src/errors.test.ts

@@ -1,7 +1,7 @@
 import {beforeEach, describe, expect, it, mock} from "bun:test";
 import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
-import {Schema} from "mongoose";
+import mongoose, {Schema} from "mongoose";
 
 import {
   APIError,
@@ -299,4 +299,22 @@ describe("apiErrorMiddleware", () => {
     expect(next).toHaveBeenCalledWith(err);
     expect(res.status).not.toHaveBeenCalled();
   });
+
+  it("converts Mongoose CastError to a 400 APIError response", () => {
+    const err = new mongoose.Error.CastError("Number", "not-a-number", "general.maxUploadSizeMb");
+    apiErrorMiddleware(err, req, res as unknown as Response, next as unknown as NextFunction);
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        meta: expect.objectContaining({
+          fields: expect.objectContaining({
+            "general.maxUploadSizeMb": expect.stringContaining("Expected Number"),
+          }),
+        }),
+        status: 400,
+        title: "Validation failed",
+      })
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
 });

package/src/errors.ts

@@ -1,7 +1,7 @@
 // https://jsonapi.org/format/#errors
 import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
-import {Schema} from "mongoose";
+import mongoose, {Schema} from "mongoose";
 
 import {logger} from "./logger";
 
@@ -42,7 +42,7 @@ export interface APIErrorConstructor {
   };
   // A meta object containing non-standard meta-information about the error.
   meta?: {[id: string]: string};
-  error?: Error;
+  error?: unknown;
   // If true, this error will not be sent to external error reporting tools like Sentry.
   disableExternalErrorTracking?: boolean;
 }
@@ -82,19 +82,17 @@ export class APIError extends Error {
       }
     | undefined;
 
-  meta: {[id: string]: any} | undefined;
+  meta: {[id: string]: unknown} | undefined;
 
-  error?: Error;
+  error?: unknown;
 
   disableExternalErrorTracking?: boolean;
 
   constructor(data: APIErrorConstructor) {
+    const errorStack =
+      data.error instanceof Error && data.error.stack ? `\n${data.error.stack}` : "";
     // Include details in when the error is printed to the console or sent to Sentry.
-    super(
-      `${data.title}${data.detail ? `: ${data.detail}` : ""}${
-        data.error ? `\n${data.error.stack}` : ""
-      }`
-    );
+    super(`${data.title}${data.detail ? `: ${data.detail}` : ""}${errorStack}`);
     this.name = "APIError";
 
     let {title, id, links, status, code, detail, source, meta, fields, error} = data;
@@ -120,9 +118,9 @@ export class APIError extends Error {
       this.meta.fields = fields;
     }
     this.error = error;
-    const logMessage = `APIError(${status}): ${title} ${detail ? detail : ""}${
-      data.error?.stack ? `\n${data.error?.stack}` : ""
-    }`;
+    const dataErrorStack =
+      data.error instanceof Error && data.error.stack ? `\n${data.error.stack}` : "";
+    const logMessage = `APIError(${status}): ${title} ${detail ? detail : ""}${dataErrorStack}`;
     if (data.disableExternalErrorTracking) {
       logger.warn(logMessage);
     } else {
@@ -162,8 +160,24 @@ export const errorsPlugin = (schema: Schema): void => {
   schema.add({apiErrors: errorSchema});
 };
 
-export const isAPIError = (error: Error): error is APIError => {
-  return error.name === "APIError";
+export const isAPIError = (error: unknown): error is APIError => {
+  return error instanceof Error && error.name === "APIError";
+};
+
+/** Extract a human-readable message from an unknown error. */
+export const errorMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+/** Extract a stack trace string from an unknown error. */
+export const errorStack = (error: unknown): string => {
+  if (error instanceof Error && error.stack) {
+    return error.stack;
+  }
+  return String(error);
 };
 
 /**
@@ -186,8 +200,9 @@ export const getDisableExternalErrorTracking = (error: unknown): boolean | undef
 // Creates an APIError body to send to clients as JSON. Errors don't have a toJSON defined,
 // and we want to strip out things like message, name, and stack for the client.
 // There is almost certainly a more elegant solution to this.
-export const getAPIErrorBody = (error: APIError): {[id: string]: any} => {
-  const errorData = {status: error.status, title: error.title};
+export const getAPIErrorBody = (error: APIError): Record<string, unknown> => {
+  const errorData: Record<string, unknown> = {status: error.status, title: error.title};
+  const indexable = error as unknown as Record<string, unknown>;
   for (const key of [
     "id",
     "links",
@@ -198,8 +213,8 @@ export const getAPIErrorBody = (error: APIError): {[id: string]: any} => {
     "meta",
     "disableExternalErrorTracking",
   ]) {
-    if (error[key]) {
-      errorData[key] = error[key];
+    if (indexable[key]) {
+      errorData[key] = indexable[key];
     }
   }
   return errorData;
@@ -219,6 +234,40 @@ export const apiUnauthorizedMiddleware = (
   }
 };
 
+/**
+ * Converts Mongoose validation/cast errors into client-friendly APIErrors.
+ */
+export const mongooseErrorToAPIError = (err: Error): APIError | null => {
+  if (err instanceof mongoose.Error.ValidationError) {
+    const fields: {[id: string]: string} = {};
+    for (const [path, subErr] of Object.entries(err.errors)) {
+      fields[path] = subErr.message;
+    }
+    return new APIError({
+      detail: err.message,
+      disableExternalErrorTracking: true,
+      fields,
+      status: 400,
+      title: "Validation failed",
+    });
+  }
+
+  if (err instanceof mongoose.Error.CastError) {
+    const path = err.path ?? "field";
+    return new APIError({
+      detail: `Invalid value for ${path}`,
+      disableExternalErrorTracking: true,
+      fields: {
+        [path]: `Expected ${err.kind ?? "a valid value"}, got ${JSON.stringify(err.value)}`,
+      },
+      status: 400,
+      title: "Validation failed",
+    });
+  }
+
+  return null;
+};
+
 export const apiErrorMiddleware = (
   err: Error,
   _req: Request,
@@ -230,7 +279,32 @@ export const apiErrorMiddleware = (
       Sentry.captureException(err);
     }
     res.status(err.status).json(getAPIErrorBody(err)).send();
-  } else {
-    next(err);
+    return;
+  }
+
+  const mongooseError = mongooseErrorToAPIError(err);
+  if (mongooseError) {
+    res.status(mongooseError.status).json(getAPIErrorBody(mongooseError)).send();
+    return;
+  }
+
+  next(err);
+};
+
+/**
+ * Final Express error handler for unexpected errors. Always returns JSON so
+ * clients (e.g. RTK Query) can parse the response.
+ */
+export const apiFallthroughErrorMiddleware = (
+  err: Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  logger.error(`Fallthrough error: ${err}${err.stack ? `\n${err.stack}` : ""}`);
+  Sentry.captureException(err);
+  if (res.headersSent) {
+    return;
   }
+  res.status(500).json({status: 500, title: "Internal server error"}).send();
 };