@terreno/api 0.13.3 → 0.14.1

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();
+  });
 });