@terreno/api 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.20.0
+
+### Changed (breaking)
+
+- **`ConfigurationApp` `POST {basePath}/list-secrets` no longer persists secret values.** Previously it resolved secrets from the provider and wrote the resolved plaintext values into the configuration document. It is now a **read-only validation/status** endpoint: it reports, per secret field, only non-sensitive metadata (`path`, `secretName`, `version`, and a boolean `resolvable`/`isConfigured`) and never writes to the document or returns secret values. A `POST {basePath}/validate-secrets` alias with the same behavior is also registered.
+- **`ConfigurationApp` `PATCH {basePath}` strips `secret: true` fields** from the incoming body, so a secret value can never be written through the update path. Secret fields are read-only via this surface.
+- **`configurationPlugin` no longer adds the `_singleton` unique index by default.** It is now opt-in via `enforceSingletonIndex: true` so it does not double-enforce or conflict with consumers that already guarantee a single non-deleted document via the pre-save guard or their own soft-delete plugin/indexes.
+- **`configurationPlugin` singleton semantics are now soft-delete aware.** `getConfig`, `updateConfig`, and the pre-save guard operate on `{deleted: false}` when the schema has a `deleted` path (e.g. via `isDeletedPlugin`). A soft-deleted document no longer blocks creating a new singleton; hard deletes (`deleteOne`/`deleteMany`/`findOneAndDelete`) remain blocked.
+- **`configurationPlugin.updateConfig` now applies updates via `findOneAndUpdate({$set})` with dotted paths** instead of `Object.assign` + `doc.save()`. This preserves sibling fields inside nested subdocuments on partial patches and tolerates legacy/out-of-schema fields already persisted under `strict: "throw"`.
+
+### Added
+
+- **`SecretProvider.getSecret(secretName, version?)`** — optional `version` parameter. `GcpSecretProvider` resolves `projects/{projectId}/secrets/{name}/versions/{version}` (default `latest`, full resource paths still honored); `EnvSecretProvider` ignores it. Secret fields can declare a `secretVersion` schema option, surfaced on `SecretFieldMeta.version` and passed through `resolveSecrets`.
+- **`CompositeSecretProvider`** — composes an ordered list of providers and returns the first non-null result; a failing provider is warn-logged (secret name only) and resolution falls through to the next.
+- **`CachingSecretProvider`** — wraps any provider with an in-memory TTL cache keyed by `secretName@version`, with `clear()` / `clearKey()` for rotation and tests. Caches `null` results. Never logs values.
+- **`ConfigurationApp` pluggable permissions** — `permissions: {read?, update?, meta?, listSecrets?}` accepts terreno permission functions (e.g. `[IsStaff]`), AND-combined like `modelRouter`. Defaults to admin-only for every route.
+- **`ConfigurationApp` lifecycle hooks** — `preUpdate(body, req)` (validate/normalize) and `postUpdate(config, prevValue, req)` (audit logging). Both payloads have secret values redacted.
+- **`flattenToDotPaths`** — exported helper used by `updateConfig`.
+
+### Migration
+
+- If you relied on `list-secrets` to populate secret values into the configuration document, stop. Resolve secrets on-demand at runtime via `Model.resolveSecrets(provider)` (returns an in-memory `Map`) and read them from memory; never persist them.
+- If you depended on the `_singleton` unique index, pass `configurationPlugin(schema, {enforceSingletonIndex: true})`.
+- For GCP-with-env-fallback and caching, compose `new CachingSecretProvider(new CompositeSecretProvider([gcp, env]), {ttlMs})`.
+
 ## 0.16.0
 
 ### Added

package/dist/auth.js

@@ -90,6 +90,7 @@ exports.addMeRoutes = exports.addAuthRoutes = exports.setupAuth = exports.genera
 var node_crypto_1 = require("node:crypto");
 var express_1 = __importDefault(require("express"));
 var jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+var luxon_1 = require("luxon");
 var ms_1 = __importDefault(require("ms"));
 var passport_1 = __importDefault(require("passport"));
 var passport_anonymous_1 = require("passport-anonymous");
@@ -247,7 +248,6 @@ var generateTokens = function (user_1, authOptions_1) {
     });
 };
 exports.generateTokens = generateTokens;
-// TODO allow customization
 var setupAuth = function (app, userModel) {
     passport_1.default.use(new passport_anonymous_1.Strategy());
     passport_1.default.use(userModel.createStrategy());
@@ -371,7 +371,7 @@ var setupAuth = function (app, userModel) {
                             ? error.expiredAt
                             : undefined;
                         message = (0, errors_1.errorMessage)(error);
-                        details = "[jwt] Error decoding token".concat(userText, ": ").concat(error, ", expired at ").concat(expiredAt, ", current time: ").concat(Date.now());
+                        details = "[jwt] Error decoding token".concat(userText, ": ").concat(error, ", expired at ").concat(expiredAt, ", current time: ").concat(luxon_1.DateTime.now().toMillis());
                         logger_1.logger.debug(details);
                         return [2 /*return*/, res.status(401).json({ details: details, message: message })];
                     }

package/dist/configuration.test.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -135,11 +146,7 @@ var buildApp = function (configModel, options) {
     var app = (0, tests_1.getBaseServer)();
     (0, auth_1.setupAuth)(app, tests_1.UserModel);
     (0, auth_1.addAuthRoutes)(app, tests_1.UserModel);
-    var configApp = new configurationApp_1.ConfigurationApp({
-        basePath: options === null || options === void 0 ? void 0 : options.basePath,
-        fieldOverrides: options === null || options === void 0 ? void 0 : options.fieldOverrides,
-        model: configModel,
-    });
+    var configApp = new configurationApp_1.ConfigurationApp(__assign({ model: configModel }, options));
     configApp.register(app);
     app.use(errors_1.apiUnauthorizedMiddleware);
     app.use(errors_1.apiErrorMiddleware);
@@ -268,6 +275,49 @@ var buildApp = function (configModel, options) {
                 }
             });
         }); });
+        (0, bun_test_1.it)("preserves sibling subdoc fields on a partial nested patch", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var updated;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, TestConfig.updateConfig({ general: { appName: "Initial", maintenanceMode: true } })];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, TestConfig.updateConfig({ general: { appName: "Renamed" } })];
+                    case 2:
+                        updated = _a.sent();
+                        (0, bun_test_1.expect)(updated.general.appName).toBe("Renamed");
+                        // Sibling must be preserved (not clobbered back to the default).
+                        (0, bun_test_1.expect)(updated.general.maintenanceMode).toBe(true);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("tolerates legacy/out-of-schema fields already persisted", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var updated, raw;
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: 
+                    // Insert a document containing a field that is not in the (strict: throw) schema.
+                    return [4 /*yield*/, TestConfig.getConfig()];
+                    case 1:
+                        // Insert a document containing a field that is not in the (strict: throw) schema.
+                        _c.sent();
+                        return [4 /*yield*/, ((_a = mongoose_1.default.connection.db) === null || _a === void 0 ? void 0 : _a.collection("testconfigs").updateOne({}, { $set: { legacyField: "stale" } }))];
+                    case 2:
+                        _c.sent();
+                        return [4 /*yield*/, TestConfig.updateConfig({ general: { appName: "Survives" } })];
+                    case 3:
+                        updated = _c.sent();
+                        (0, bun_test_1.expect)(updated.general.appName).toBe("Survives");
+                        return [4 /*yield*/, ((_b = mongoose_1.default.connection.db) === null || _b === void 0 ? void 0 : _b.collection("testconfigs").findOne({}))];
+                    case 4:
+                        raw = _c.sent();
+                        (0, bun_test_1.expect)(raw === null || raw === void 0 ? void 0 : raw.legacyField).toBe("stale");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
     });
     (0, bun_test_1.describe)("singleton enforcement", function () {
         (0, bun_test_1.it)("prevents creating a second document via save", function () { return __awaiter(void 0, void 0, void 0, function () {
@@ -567,17 +617,23 @@ var buildApp = function (configModel, options) {
                 }
             });
         }); });
-        (0, bun_test_1.it)("redacts secrets in the response", function () { return __awaiter(void 0, void 0, void 0, function () {
-            var res;
+        (0, bun_test_1.it)("never persists secret field values supplied in the body", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res, stored;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0: return [4 /*yield*/, adminAgent
                             .patch("/configuration")
-                            .send({ integrations: { apiKey: "new-secret" } })
+                            .send({ integrations: { apiKey: "new-secret", webhookUrl: "https://changed.example.com" } })
                             .expect(200)];
                     case 1:
                         res = _a.sent();
-                        (0, bun_test_1.expect)(res.body.data.integrations.apiKey).toBe("********");
+                        // Secret stays empty (stripped); non-secret sibling is updated.
+                        (0, bun_test_1.expect)(res.body.data.integrations.apiKey).toBe("");
+                        (0, bun_test_1.expect)(res.body.data.integrations.webhookUrl).toBe("https://changed.example.com");
+                        return [4 /*yield*/, TestConfig.getConfig()];
+                    case 2:
+                        stored = _a.sent();
+                        (0, bun_test_1.expect)(stored.integrations.apiKey).toBe("");
                         return [2 /*return*/];
                 }
             });
@@ -597,7 +653,7 @@ var buildApp = function (configModel, options) {
         }); });
     });
     (0, bun_test_1.describe)("POST /configuration/list-secrets", function () {
-        (0, bun_test_1.it)("returns discovered secret fields", function () { return __awaiter(void 0, void 0, void 0, function () {
+        (0, bun_test_1.it)("returns discovered secret fields with resolvable status", function () { return __awaiter(void 0, void 0, void 0, function () {
             var res;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -607,6 +663,42 @@ var buildApp = function (configModel, options) {
                         (0, bun_test_1.expect)(res.body.secretFields).toHaveLength(1);
                         (0, bun_test_1.expect)(res.body.secretFields[0].path).toBe("integrations.apiKey");
                         (0, bun_test_1.expect)(res.body.secretFields[0].secretName).toBe("external-api-key");
+                        // No provider configured -> not resolvable, and no value is ever returned.
+                        (0, bun_test_1.expect)(res.body.secretFields[0].resolvable).toBe(false);
+                        (0, bun_test_1.expect)(res.body.secretFields[0].isConfigured).toBe(false);
+                        (0, bun_test_1.expect)(JSON.stringify(res.body)).not.toContain("super-secret");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("does not mutate the stored config document's secret fields", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var stored;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, TestConfig.getConfig()];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, adminAgent.post("/configuration/list-secrets").expect(200)];
+                    case 2:
+                        _a.sent();
+                        return [4 /*yield*/, TestConfig.getConfig()];
+                    case 3:
+                        stored = _a.sent();
+                        // list-secrets must never write resolved values into the document.
+                        (0, bun_test_1.expect)(stored.integrations.apiKey).toBe("");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("is also exposed as validate-secrets", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, adminAgent.post("/configuration/validate-secrets").expect(200)];
+                    case 1:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.secretFields).toHaveLength(1);
+                        (0, bun_test_1.expect)(res.body.secretFields[0].path).toBe("integrations.apiKey");
                         return [2 /*return*/];
                 }
             });
@@ -698,3 +790,190 @@ var buildApp = function (configModel, options) {
         });
     }); });
 });
+(0, bun_test_1.describe)("ConfigurationApp with custom permissions", function () {
+    var app;
+    var adminAgent;
+    var notAdminAgent;
+    // Terreno-style permission: any authenticated user (not just admins).
+    var isAuthenticated = function (_method, user) { return Boolean(user === null || user === void 0 ? void 0 : user.id); };
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _b.sent();
+                    return [4 /*yield*/, ((_a = mongoose_1.default.connection.db) === null || _a === void 0 ? void 0 : _a.collection("testconfigs").deleteMany({}))];
+                case 2:
+                    _b.sent();
+                    app = buildApp(TestConfig, {
+                        permissions: {
+                            read: [isAuthenticated],
+                            // update intentionally left default (admin-only)
+                        },
+                    });
+                    return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                case 3:
+                    adminAgent = _b.sent();
+                    return [4 /*yield*/, (0, tests_1.authAsUser)(app, "notAdmin")];
+                case 4:
+                    notAdminAgent = _b.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("allows non-admin reads when a custom read permission is supplied", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, notAdminAgent.get("/configuration").expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data.general.appName).toBe("Test App");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("still rejects unauthenticated reads", function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, (0, supertest_1.default)(app).get("/configuration").expect(401)];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("keeps update admin-only by default", function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, notAdminAgent
+                        .patch("/configuration")
+                        .send({ general: { appName: "Nope" } })
+                        .expect(403)];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, adminAgent
+                            .patch("/configuration")
+                            .send({ general: { appName: "Yes" } })
+                            .expect(200)];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+(0, bun_test_1.describe)("ConfigurationApp with update hooks", function () {
+    var app;
+    var adminAgent;
+    var preUpdateCalls;
+    var postUpdateCalls;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _b.sent();
+                    return [4 /*yield*/, ((_a = mongoose_1.default.connection.db) === null || _a === void 0 ? void 0 : _a.collection("testconfigs").deleteMany({}))];
+                case 2:
+                    _b.sent();
+                    preUpdateCalls = [];
+                    postUpdateCalls = [];
+                    app = buildApp(TestConfig, {
+                        postUpdate: function (config, prevValue) { return __awaiter(void 0, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                postUpdateCalls.push({ config: config, prev: prevValue });
+                                return [2 /*return*/];
+                            });
+                        }); },
+                        preUpdate: function (body) { return __awaiter(void 0, void 0, void 0, function () {
+                            var general;
+                            var _a;
+                            return __generator(this, function (_b) {
+                                preUpdateCalls.push(body);
+                                general = (_a = body.general) !== null && _a !== void 0 ? _a : {};
+                                return [2 /*return*/, __assign(__assign({}, body), { general: __assign(__assign({}, general), { maintenanceMode: true }) })];
+                            });
+                        }); },
+                    });
+                    return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                case 3:
+                    adminAgent = _b.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("runs preUpdate to transform the body before applying", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, adminAgent
+                        .patch("/configuration")
+                        .send({ general: { appName: "Hooked" } })
+                        .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data.general.appName).toBe("Hooked");
+                    (0, bun_test_1.expect)(res.body.data.general.maintenanceMode).toBe(true);
+                    (0, bun_test_1.expect)(preUpdateCalls).toHaveLength(1);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not persist secret values even if preUpdate re-introduces them", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var leakyApp, agent, res, stored;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    leakyApp = buildApp(TestConfig, {
+                        preUpdate: function (body) { return (__assign(__assign({}, body), { integrations: __assign(__assign({}, body.integrations), { apiKey: "leaked-secret" }) })); },
+                    });
+                    return [4 /*yield*/, (0, tests_1.authAsUser)(leakyApp, "admin")];
+                case 1:
+                    agent = _a.sent();
+                    return [4 /*yield*/, agent
+                            .patch("/configuration")
+                            .send({ general: { appName: "Safe" } })
+                            .expect(200)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.data.general.appName).toBe("Safe");
+                    (0, bun_test_1.expect)(res.body.data.integrations.apiKey).toBe("");
+                    return [4 /*yield*/, TestConfig.getConfig()];
+                case 3:
+                    stored = _a.sent();
+                    (0, bun_test_1.expect)(stored.integrations.apiKey).toBe("");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("runs postUpdate with redacted config and previous value", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, config, prev;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: 
+                // Seed a secret so we can confirm it is redacted in hook payloads.
+                return [4 /*yield*/, TestConfig.updateConfig({ integrations: { apiKey: "should-not-leak" } })];
+                case 1:
+                    // Seed a secret so we can confirm it is redacted in hook payloads.
+                    _b.sent();
+                    return [4 /*yield*/, adminAgent
+                            .patch("/configuration")
+                            .send({ general: { appName: "Audited" } })
+                            .expect(200)];
+                case 2:
+                    _b.sent();
+                    (0, bun_test_1.expect)(postUpdateCalls).toHaveLength(1);
+                    _a = postUpdateCalls[0], config = _a.config, prev = _a.prev;
+                    (0, bun_test_1.expect)(config.general.appName).toBe("Audited");
+                    // Secret values must be redacted in both payloads.
+                    (0, bun_test_1.expect)(config.integrations.apiKey).toBe("********");
+                    (0, bun_test_1.expect)(prev.integrations.apiKey).toBe("********");
+                    (0, bun_test_1.expect)(JSON.stringify(postUpdateCalls)).not.toContain("should-not-leak");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/dist/configurationApp.d.ts

@@ -1,5 +1,6 @@
 import type express from "express";
 import type { Model } from "mongoose";
+import { type PermissionMethod } from "./permissions";
 import type { TerrenoPlugin } from "./terrenoPlugin";
 /**
  * Metadata for a single configuration field, sent to the frontend.
@@ -28,6 +29,44 @@ interface ConfigSectionMeta {
 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.
  */
@@ -40,17 +79,37 @@ export interface ConfigurationAppOptions {
     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;
 }
 /**
  * TerrenoPlugin that provides configuration management endpoints.
  *
  * 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.
@@ -72,13 +131,21 @@ export interface ConfigurationAppOptions {
  * 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();
  * ```
  */
 export declare class ConfigurationApp implements TerrenoPlugin {
     private options;
     constructor(options: ConfigurationAppOptions);
+    /**
+     * Resolves the guard middleware for a route: the consumer's terreno permission
+     * functions when supplied, otherwise the default admin-only guard.
+     */
+    private guardFor;
     register(app: express.Application): void;
     /**
      * Builds the metadata response by inspecting the model schema.