@terreno/api 0.19.0 → 0.20.0

package/src/configuration.test.ts

@@ -93,16 +93,15 @@ const ScalarConfig = (mongoose.models.ScalarConfig ||
 
 const buildApp = (
   configModel: mongoose.Model<any>,
-  options?: {basePath?: string; fieldOverrides?: Record<string, {widget?: string}>}
+  options?: Partial<Omit<ConstructorParameters<typeof ConfigurationApp>[0], "model">>
 ): express.Application => {
   const app = getBaseServer();
   setupAuth(app, UserModel as any);
   addAuthRoutes(app, UserModel as any);
 
   const configApp = new ConfigurationApp({
-    basePath: options?.basePath,
-    fieldOverrides: options?.fieldOverrides,
     model: configModel,
+    ...options,
   });
   configApp.register(app);
 
@@ -168,6 +167,31 @@ describe("configurationPlugin", () => {
       expect(updated.general.appName).toBe("Changed");
       expect(updated.general.maintenanceMode).toBe(true);
     });
+
+    it("preserves sibling subdoc fields on a partial nested patch", async () => {
+      await TestConfig.updateConfig({general: {appName: "Initial", maintenanceMode: true}});
+      // Patch only one field within the nested subdoc.
+      const updated = await TestConfig.updateConfig({general: {appName: "Renamed"}});
+      expect(updated.general.appName).toBe("Renamed");
+      // Sibling must be preserved (not clobbered back to the default).
+      expect(updated.general.maintenanceMode).toBe(true);
+    });
+
+    it("tolerates legacy/out-of-schema fields already persisted", async () => {
+      // Insert a document containing a field that is not in the (strict: throw) schema.
+      await TestConfig.getConfig();
+      await mongoose.connection.db
+        ?.collection("testconfigs")
+        .updateOne({}, {$set: {legacyField: "stale"}});
+
+      // A full doc.save() would throw under strict: "throw"; $set must not.
+      const updated = await TestConfig.updateConfig({general: {appName: "Survives"}});
+      expect(updated.general.appName).toBe("Survives");
+
+      // The legacy field is left untouched on the document.
+      const raw = await mongoose.connection.db?.collection("testconfigs").findOne({});
+      expect(raw?.legacyField).toBe("stale");
+    });
   });
 
   describe("singleton enforcement", () => {
@@ -327,12 +351,18 @@ describe("ConfigurationApp routes", () => {
       expect(res.body.data.general.appName).toBe("New Name");
     });
 
-    it("redacts secrets in the response", async () => {
+    it("never persists secret field values supplied in the body", async () => {
       const res = await adminAgent
         .patch("/configuration")
-        .send({integrations: {apiKey: "new-secret"}})
+        .send({integrations: {apiKey: "new-secret", webhookUrl: "https://changed.example.com"}})
         .expect(200);
-      expect(res.body.data.integrations.apiKey).toBe("********");
+      // Secret stays empty (stripped); non-secret sibling is updated.
+      expect(res.body.data.integrations.apiKey).toBe("");
+      expect(res.body.data.integrations.webhookUrl).toBe("https://changed.example.com");
+
+      // Confirm the raw stored document holds no secret value.
+      const stored = await (TestConfig as any).getConfig();
+      expect(stored.integrations.apiKey).toBe("");
     });
 
     it("returns 403 for non-admin", async () => {
@@ -344,11 +374,29 @@ describe("ConfigurationApp routes", () => {
   });
 
   describe("POST /configuration/list-secrets", () => {
-    it("returns discovered secret fields", async () => {
+    it("returns discovered secret fields with resolvable status", async () => {
       const res = await adminAgent.post("/configuration/list-secrets").expect(200);
       expect(res.body.secretFields).toHaveLength(1);
       expect(res.body.secretFields[0].path).toBe("integrations.apiKey");
       expect(res.body.secretFields[0].secretName).toBe("external-api-key");
+      // No provider configured -> not resolvable, and no value is ever returned.
+      expect(res.body.secretFields[0].resolvable).toBe(false);
+      expect(res.body.secretFields[0].isConfigured).toBe(false);
+      expect(JSON.stringify(res.body)).not.toContain("super-secret");
+    });
+
+    it("does not mutate the stored config document's secret fields", async () => {
+      await (TestConfig as any).getConfig();
+      await adminAgent.post("/configuration/list-secrets").expect(200);
+      const stored = await (TestConfig as any).getConfig();
+      // list-secrets must never write resolved values into the document.
+      expect(stored.integrations.apiKey).toBe("");
+    });
+
+    it("is also exposed as validate-secrets", async () => {
+      const res = await adminAgent.post("/configuration/validate-secrets").expect(200);
+      expect(res.body.secretFields).toHaveLength(1);
+      expect(res.body.secretFields[0].path).toBe("integrations.apiKey");
     });
 
     it("returns 403 for non-admin", async () => {
@@ -397,3 +445,119 @@ describe("ConfigurationApp with field overrides", () => {
     expect(intSection.fields.webhookUrl.widget).toBe("url");
   });
 });
+
+describe("ConfigurationApp with custom permissions", () => {
+  let app: express.Application;
+  let adminAgent: TestAgent;
+  let notAdminAgent: TestAgent;
+
+  // Terreno-style permission: any authenticated user (not just admins).
+  const isAuthenticated = (_method: any, user?: any): boolean => Boolean(user?.id);
+
+  beforeEach(async () => {
+    await setupDb();
+    await mongoose.connection.db?.collection("testconfigs").deleteMany({});
+    app = buildApp(TestConfig, {
+      permissions: {
+        read: [isAuthenticated],
+        // update intentionally left default (admin-only)
+      },
+    });
+    adminAgent = await authAsUser(app, "admin");
+    notAdminAgent = await authAsUser(app, "notAdmin");
+  });
+
+  it("allows non-admin reads when a custom read permission is supplied", async () => {
+    const res = await notAdminAgent.get("/configuration").expect(200);
+    expect(res.body.data.general.appName).toBe("Test App");
+  });
+
+  it("still rejects unauthenticated reads", async () => {
+    await supertest(app).get("/configuration").expect(401);
+  });
+
+  it("keeps update admin-only by default", async () => {
+    await notAdminAgent
+      .patch("/configuration")
+      .send({general: {appName: "Nope"}})
+      .expect(403);
+    await adminAgent
+      .patch("/configuration")
+      .send({general: {appName: "Yes"}})
+      .expect(200);
+  });
+});
+
+describe("ConfigurationApp with update hooks", () => {
+  let app: express.Application;
+  let adminAgent: TestAgent;
+  let preUpdateCalls: Array<Record<string, unknown>>;
+  let postUpdateCalls: Array<{config: Record<string, unknown>; prev: Record<string, unknown>}>;
+
+  beforeEach(async () => {
+    await setupDb();
+    await mongoose.connection.db?.collection("testconfigs").deleteMany({});
+    preUpdateCalls = [];
+    postUpdateCalls = [];
+    app = buildApp(TestConfig, {
+      postUpdate: async (config, prevValue) => {
+        postUpdateCalls.push({config, prev: prevValue});
+      },
+      preUpdate: async (body) => {
+        preUpdateCalls.push(body);
+        // Normalize: force maintenanceMode on.
+        const general = (body.general as Record<string, unknown>) ?? {};
+        return {...body, general: {...general, maintenanceMode: true}};
+      },
+    });
+    adminAgent = await authAsUser(app, "admin");
+  });
+
+  it("runs preUpdate to transform the body before applying", async () => {
+    const res = await adminAgent
+      .patch("/configuration")
+      .send({general: {appName: "Hooked"}})
+      .expect(200);
+    expect(res.body.data.general.appName).toBe("Hooked");
+    expect(res.body.data.general.maintenanceMode).toBe(true);
+    expect(preUpdateCalls).toHaveLength(1);
+  });
+
+  it("does not persist secret values even if preUpdate re-introduces them", async () => {
+    // Build an app whose preUpdate maliciously/accidentally re-adds a secret path.
+    const leakyApp = buildApp(TestConfig, {
+      preUpdate: (body) => ({
+        ...body,
+        integrations: {...(body.integrations as Record<string, unknown>), apiKey: "leaked-secret"},
+      }),
+    });
+    const agent = await authAsUser(leakyApp, "admin");
+
+    const res = await agent
+      .patch("/configuration")
+      .send({general: {appName: "Safe"}})
+      .expect(200);
+    expect(res.body.data.general.appName).toBe("Safe");
+    expect(res.body.data.integrations.apiKey).toBe("");
+
+    const stored = await (TestConfig as any).getConfig();
+    expect(stored.integrations.apiKey).toBe("");
+  });
+
+  it("runs postUpdate with redacted config and previous value", async () => {
+    // Seed a secret so we can confirm it is redacted in hook payloads.
+    await (TestConfig as any).updateConfig({integrations: {apiKey: "should-not-leak"}});
+    await adminAgent
+      .patch("/configuration")
+      .send({general: {appName: "Audited"}})
+      .expect(200);
+
+    expect(postUpdateCalls).toHaveLength(1);
+    const {config, prev} = postUpdateCalls[0];
+    expect((config.general as any).appName).toBe("Audited");
+    // Secret values must be redacted in both payloads.
+    expect((config.integrations as any).apiKey).toBe("********");
+    expect((prev.integrations as any).apiKey).toBe("********");
+    expect(JSON.stringify(postUpdateCalls)).not.toContain("should-not-leak");
+  });
+});

package/src/configurationApp.ts

@@ -1,16 +1,18 @@
 import type express from "express";
 import type {Model, Schema} from "mongoose";
 
-import {asyncHandler} from "./api";
+import {asyncHandler, type RESTMethod} from "./api";
 import {authenticateMiddleware} from "./auth";
 import type {SecretFieldMeta} from "./configurationPlugin";
 import {APIError} from "./errors";
 import {logger} from "./logger";
+import {checkPermissions, type PermissionMethod} from "./permissions";
 import {getOpenApiSpecForModel} from "./populate";
 import type {TerrenoPlugin} from "./terrenoPlugin";
 
 /**
- * Middleware that requires the user to be an admin.
+ * Middleware that requires the user to be an admin. Used as the default guard
+ * for every configuration route when no custom `permissions` are supplied.
  */
 const requireAdmin = (
   req: express.Request,
@@ -24,6 +26,29 @@ const requireAdmin = (
   next();
 };
 
+/**
+ * Builds an Express middleware that AND-combines terreno permission functions
+ * (the same {@link PermissionMethod} contract used by `modelRouter`). The
+ * configuration singleton has no per-object ownership, so the loaded config
+ * document is passed as the permission object.
+ */
+const buildPermissionMiddleware = (
+  perms: PermissionMethod<unknown>[],
+  method: RESTMethod,
+  loadObj?: () => Promise<unknown>
+): express.RequestHandler =>
+  asyncHandler(async (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    const obj = loadObj ? await loadObj() : undefined;
+    const allowed = await checkPermissions(method, perms, req.user, obj);
+    if (!allowed) {
+      throw new APIError({
+        status: 403,
+        title: "Access to configuration denied",
+      });
+    }
+    next();
+  });
+
 /**
  * Metadata for a single configuration field, sent to the frontend.
  */
@@ -54,6 +79,54 @@ export interface ConfigurationMetaResponse {
   sections: ConfigSectionMeta[];
 }
 
+/**
+ * Per-route permission overrides for ConfigurationApp. Each value is an array of
+ * terreno permission functions ({@link PermissionMethod}), AND-combined like
+ * `modelRouter` permissions. When a route is omitted, the default admin-only
+ * guard applies.
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   read: [IsStaff],
+ *   update: [IsSuperUser],
+ * }
+ * ```
+ */
+export interface ConfigurationPermissions {
+  /** Guards `GET {basePath}` (current values). */
+  read?: PermissionMethod<unknown>[];
+  /** Guards `PATCH {basePath}` (update values). */
+  update?: PermissionMethod<unknown>[];
+  /** Guards `GET {basePath}/meta` (schema metadata). */
+  meta?: PermissionMethod<unknown>[];
+  /** Guards `POST {basePath}/list-secrets` and `/validate-secrets`. */
+  listSecrets?: PermissionMethod<unknown>[];
+}
+
+/**
+ * Hook invoked before a configuration update is applied. Receives the incoming
+ * (already system-field- and secret-field-stripped) body and the request, and
+ * returns the body to apply. Use it to validate or normalize input. Throw an
+ * {@link APIError} to reject the update.
+ */
+export type ConfigurationPreUpdateHook = (
+  body: Record<string, unknown>,
+  req: express.Request
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/**
+ * Hook invoked after a configuration update is applied. Receives the updated
+ * configuration and the previous value (both with secret values redacted) plus
+ * the request, enabling audit logging of who changed what. Secret values are
+ * never included.
+ */
+export type ConfigurationPostUpdateHook = (
+  config: Record<string, unknown>,
+  prevValue: Record<string, unknown>,
+  req: express.Request
+) => void | Promise<void>;
+
 /**
  * Options for ConfigurationApp.
  */
@@ -65,6 +138,16 @@ export interface ConfigurationAppOptions {
   basePath?: string;
   /** Per-field widget overrides (e.g., {"ai.systemPrompt": "markdown"}). */
   fieldOverrides?: Record<string, {widget?: string}>;
+  /**
+   * Per-route permission overrides. Defaults to admin-only for every route when
+   * omitted. Supply terreno permission functions (e.g. `[IsStaff]`) to expose
+   * configuration to a consumer's own permission system.
+   */
+  permissions?: ConfigurationPermissions;
+  /** Hook run before an update is applied (validation/normalization). */
+  preUpdate?: ConfigurationPreUpdateHook;
+  /** Hook run after an update is applied (audit logging). */
+  postUpdate?: ConfigurationPostUpdateHook;
 }
 
 /**
@@ -152,6 +235,41 @@ const redactSecrets = (
   return redacted;
 };
 
+/**
+ * Removes secret field values from an incoming update body so a secret value can
+ * never be written to the configuration document through the update path.
+ * Copies nodes along each secret path to avoid mutating the caller's object.
+ */
+const stripSecretFields = (
+  obj: Record<string, unknown>,
+  secretFields: SecretFieldMeta[]
+): Record<string, unknown> => {
+  const stripped: Record<string, unknown> = {...obj};
+  for (const field of secretFields) {
+    const parts = field.path.split(".");
+    let current: Record<string, unknown> | null = stripped;
+    for (let i = 0; i < parts.length - 1; 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;
+      }
+    }
+    if (current != null) {
+      delete current[parts[parts.length - 1]];
+    }
+  }
+  return stripped;
+};
+
 /**
  * Converts a camelCase or PascalCase string into a display-friendly title.
  */
@@ -167,11 +285,21 @@ const toDisplayName = (name: string): string => {
  *
  * Inspects the Mongoose configuration model to auto-generate:
  * - `GET {basePath}/meta` — Schema metadata (sections, fields, types, descriptions)
- * - `GET {basePath}` — Current configuration values
- * - `PATCH {basePath}` — Update configuration values
- * - `POST {basePath}/refresh-secrets` — Trigger secret refresh (if provider configured)
+ * - `GET {basePath}` — Current configuration values (secret values redacted)
+ * - `PATCH {basePath}` — Update configuration values (secret fields stripped; never written)
+ * - `POST {basePath}/list-secrets` (alias `POST {basePath}/validate-secrets`) —
+ *   Read-only status of each secret field (whether the provider can resolve it).
+ *   This endpoint never resolves values into the document and returns no secret values.
+ *
+ * By default all endpoints require `Permissions.IsAdmin`. Supply `permissions`
+ * to gate routes with a consumer's own permission functions, and `preUpdate`/
+ * `postUpdate` hooks to validate and audit-log changes. This makes
+ * `ConfigurationApp` suitable as a single, consumer-owned configuration surface
+ * that can replace a bespoke config router.
  *
- * All endpoints require `Permissions.IsAdmin`.
+ * Secret values never touch the database, logs, audit payloads, or API
+ * responses: secret fields are stripped from incoming updates and redacted on
+ * every read.
  *
  * Nested subschemas in the model become separate sections in the metadata,
  * making them renderable as cards/accordions in the admin UI.
@@ -193,7 +321,10 @@ const toDisplayName = (name: string): string => {
  * const AppConfig = mongoose.model("AppConfig", configSchema);
  *
  * new TerrenoApp({ userModel: User })
- *   .configure(AppConfig)
+ *   .configure(AppConfig, {
+ *     permissions: {read: [IsStaff], update: [IsSuperUser]},
+ *     postUpdate: (config, prevValue, req) => auditLog(req.user, prevValue, config),
+ *   })
  *   .start();
  * ```
  */
@@ -204,6 +335,21 @@ export class ConfigurationApp implements TerrenoPlugin {
     this.options = options;
   }
 
+  /**
+   * Resolves the guard middleware for a route: the consumer's terreno permission
+   * functions when supplied, otherwise the default admin-only guard.
+   */
+  private guardFor(
+    route: keyof ConfigurationPermissions,
+    method: RESTMethod
+  ): express.RequestHandler {
+    const perms = this.options.permissions?.[route];
+    if (perms && perms.length > 0) {
+      return buildPermissionMiddleware(perms, method);
+    }
+    return requireAdmin;
+  }
+
   register(app: express.Application): void {
     const basePath = this.options.basePath ?? "/configuration";
     const ConfigModel = this.options.model;
@@ -216,7 +362,7 @@ export class ConfigurationApp implements TerrenoPlugin {
     app.get(
       `${basePath}/meta`,
       authenticateMiddleware(),
-      requireAdmin,
+      this.guardFor("meta", "read"),
       (_req: express.Request, res: express.Response) => {
         return res.json(meta);
       }
@@ -239,7 +385,7 @@ export class ConfigurationApp implements TerrenoPlugin {
     app.get(
       `${basePath}`,
       authenticateMiddleware(),
-      requireAdmin,
+      this.guardFor("read", "read"),
       asyncHandler(async (_req: express.Request, res: express.Response) => {
         const config = await ConfigStatics.getConfig();
         const data = redactSecrets(config.toJSON(), secretFields);
@@ -247,44 +393,81 @@ export class ConfigurationApp implements TerrenoPlugin {
       })
     );
 
-    // PATCH /configuration — update values (secrets redacted in response)
+    // PATCH /configuration — update values (secret fields stripped; secrets redacted in response)
     app.patch(
       `${basePath}`,
       authenticateMiddleware(),
-      requireAdmin,
+      this.guardFor("update", "update"),
       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;
+        // Strip internal system fields that should never be updated via the API.
+        const {_singleton: _s, _id: _i, __v: _v, ...rest} = req.body;
+        // Strip secret fields so a secret value can never be persisted via update.
+        let safeBody = stripSecretFields(rest, secretFields);
+
+        // Allow consumers to validate/normalize before applying.
+        if (this.options.preUpdate) {
+          safeBody = await this.options.preUpdate(safeBody, req);
+          // Re-strip after the hook: preUpdate receives the raw request and could
+          // otherwise (re)introduce secret paths. Secrets must never persist here.
+          safeBody = stripSecretFields(safeBody, secretFields);
+        }
+
+        // Capture the previous (redacted) value for audit hooks.
+        let prevValue: Record<string, unknown> = {};
+        if (this.options.postUpdate) {
+          const before = await ConfigStatics.getConfig();
+          prevValue = redactSecrets(before.toJSON(), secretFields);
+        }
+
         const config = await ConfigStatics.updateConfig(safeBody);
         logger.info(`Configuration updated by ${req.user?.email ?? "unknown"}`);
         const data = redactSecrets(config.toJSON(), secretFields);
+
+        if (this.options.postUpdate) {
+          await this.options.postUpdate(data, prevValue, req);
+        }
+
         return res.json({data});
       })
     );
 
-    // POST /configuration/list-secrets — list secret fields and optionally resolve from provider
-    app.post(
-      `${basePath}/list-secrets`,
-      authenticateMiddleware(),
-      requireAdmin,
-      asyncHandler(async (_req: express.Request, res: express.Response) => {
+    // POST /configuration/list-secrets — read-only status of each secret field.
+    // Never resolves values into the document and never returns secret values.
+    const validateSecretsHandler = asyncHandler(
+      async (_req: express.Request, res: express.Response) => {
+        // In-memory resolution only — used to report whether each secret is
+        // configured/resolvable. Values are never persisted or returned.
         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 ConfigStatics.updateConfig(updates);
-          logger.info(`Refreshed ${resolved.size}/${secretFields.length} secrets`);
-        }
+        const fields = secretFields.map((s) => ({
+          isConfigured: resolved.has(s.path),
+          path: s.path,
+          resolvable: resolved.has(s.path),
+          secretName: s.secretName,
+          version: s.version,
+        }));
+        logger.info(`Validated ${resolved.size}/${secretFields.length} secrets (read-only)`);
 
         return res.json({
-          message: `Resolved ${resolved.size}/${secretFields.length} secrets.`,
+          message: `${resolved.size}/${secretFields.length} secrets resolvable.`,
           resolved: resolved.size,
-          secretFields: secretFields.map((s) => ({path: s.path, secretName: s.secretName})),
+          secretFields: fields,
           total: secretFields.length,
         });
-      })
+      }
+    );
+
+    app.post(
+      `${basePath}/list-secrets`,
+      authenticateMiddleware(),
+      this.guardFor("listSecrets", "read"),
+      validateSecretsHandler
+    );
+    // Accurate alias for the read-only validation semantics.
+    app.post(
+      `${basePath}/validate-secrets`,
+      authenticateMiddleware(),
+      this.guardFor("listSecrets", "read"),
+      validateSecretsHandler
     );
 
     logger.info(`Configuration routes mounted at ${basePath}`);