@terreno/api 0.18.0 → 0.20.0

package/dist/configurationApp.js

@@ -90,9 +90,11 @@ var api_1 = require("./api");
 var auth_1 = require("./auth");
 var errors_1 = require("./errors");
 var logger_1 = require("./logger");
+var permissions_1 = require("./permissions");
 var populate_1 = require("./populate");
 /**
- * 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.
  */
 var requireAdmin = function (req, _res, next) {
     var _a;
@@ -102,6 +104,43 @@ var requireAdmin = function (req, _res, next) {
     }
     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.
+ */
+var buildPermissionMiddleware = function (perms, method, loadObj) {
+    return (0, api_1.asyncHandler)(function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
+        var obj, _a, allowed;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    if (!loadObj) return [3 /*break*/, 2];
+                    return [4 /*yield*/, loadObj()];
+                case 1:
+                    _a = _b.sent();
+                    return [3 /*break*/, 3];
+                case 2:
+                    _a = undefined;
+                    _b.label = 3;
+                case 3:
+                    obj = _a;
+                    return [4 /*yield*/, (0, permissions_1.checkPermissions)(method, perms, req.user, obj)];
+                case 4:
+                    allowed = _b.sent();
+                    if (!allowed) {
+                        throw new errors_1.APIError({
+                            status: 403,
+                            title: "Access to configuration denied",
+                        });
+                    }
+                    next();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+};
 var extractFieldMeta = function (properties, required, schema, prefix, fieldOverrides) {
     var e_1, _a;
     var _b, _c, _d;
@@ -183,6 +222,49 @@ var redactSecrets = function (obj, secretFields) {
     }
     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.
+ */
+var stripSecretFields = function (obj, secretFields) {
+    var e_3, _a;
+    var stripped = __assign({}, obj);
+    try {
+        for (var secretFields_2 = __values(secretFields), secretFields_2_1 = secretFields_2.next(); !secretFields_2_1.done; secretFields_2_1 = secretFields_2.next()) {
+            var field = secretFields_2_1.value;
+            var parts = field.path.split(".");
+            var current = stripped;
+            for (var i = 0; i < parts.length - 1; i++) {
+                if (!current) {
+                    break;
+                }
+                var part = parts[i];
+                var nested = current[part];
+                if (nested != null && typeof nested === "object") {
+                    var copy = __assign({}, nested);
+                    current[part] = copy;
+                    current = copy;
+                }
+                else {
+                    current = null;
+                    break;
+                }
+            }
+            if (current != null) {
+                delete current[parts[parts.length - 1]];
+            }
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (secretFields_2_1 && !secretFields_2_1.done && (_a = secretFields_2.return)) _a.call(secretFields_2);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return stripped;
+};
 /**
  * Converts a camelCase or PascalCase string into a display-friendly title.
  */
@@ -197,11 +279,21 @@ var toDisplayName = function (name) {
  *
  * 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.
@@ -223,7 +315,10 @@ var toDisplayName = function (name) {
  * 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();
  * ```
  */
@@ -231,6 +326,18 @@ var ConfigurationApp = /** @class */ (function () {
     function ConfigurationApp(options) {
         this.options = options;
     }
+    /**
+     * Resolves the guard middleware for a route: the consumer's terreno permission
+     * functions when supplied, otherwise the default admin-only guard.
+     */
+    ConfigurationApp.prototype.guardFor = function (route, method) {
+        var _a;
+        var perms = (_a = this.options.permissions) === null || _a === void 0 ? void 0 : _a[route];
+        if (perms && perms.length > 0) {
+            return buildPermissionMiddleware(perms, method);
+        }
+        return requireAdmin;
+    };
     ConfigurationApp.prototype.register = function (app) {
         var _this = this;
         var _a, _b, _c;
@@ -240,14 +347,14 @@ var ConfigurationApp = /** @class */ (function () {
         // Build metadata by inspecting the schema
         var meta = this.buildMetadata(ConfigModel, schema);
         // GET /configuration/meta — schema metadata for the frontend
-        app.get("".concat(basePath, "/meta"), (0, auth_1.authenticateMiddleware)(), requireAdmin, function (_req, res) {
+        app.get("".concat(basePath, "/meta"), (0, auth_1.authenticateMiddleware)(), this.guardFor("meta", "read"), function (_req, res) {
             return res.json(meta);
         });
         var ConfigStatics = ConfigModel;
         // Discover secret fields once at registration time
         var secretFields = (_c = (_b = ConfigStatics.getSecretFields) === null || _b === void 0 ? void 0 : _b.call(ConfigStatics)) !== null && _c !== void 0 ? _c : [];
         // GET /configuration — current values (secrets redacted)
-        app.get("".concat(basePath), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+        app.get("".concat(basePath), (0, auth_1.authenticateMiddleware)(), this.guardFor("read", "read"), (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
             var config, data;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -259,61 +366,74 @@ var ConfigurationApp = /** @class */ (function () {
                 }
             });
         }); }));
-        // PATCH /configuration — update values (secrets redacted in response)
-        app.patch("".concat(basePath), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-            var _a, _s, _i, _v, safeBody, config, data;
+        // PATCH /configuration — update values (secret fields stripped; secrets redacted in response)
+        app.patch("".concat(basePath), (0, auth_1.authenticateMiddleware)(), this.guardFor("update", "update"), (0, api_1.asyncHandler)(function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var _a, _s, _i, _v, rest, safeBody, prevValue, before, config, data;
             var _b, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
                     case 0:
-                        _a = req.body, _s = _a._singleton, _i = _a._id, _v = _a.__v, safeBody = __rest(_a, ["_singleton", "_id", "__v"]);
-                        return [4 /*yield*/, ConfigStatics.updateConfig(safeBody)];
+                        _a = req.body, _s = _a._singleton, _i = _a._id, _v = _a.__v, rest = __rest(_a, ["_singleton", "_id", "__v"]);
+                        safeBody = stripSecretFields(rest, secretFields);
+                        if (!this.options.preUpdate) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.options.preUpdate(safeBody, req)];
                     case 1:
+                        safeBody = _d.sent();
+                        // 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);
+                        _d.label = 2;
+                    case 2:
+                        prevValue = {};
+                        if (!this.options.postUpdate) return [3 /*break*/, 4];
+                        return [4 /*yield*/, ConfigStatics.getConfig()];
+                    case 3:
+                        before = _d.sent();
+                        prevValue = redactSecrets(before.toJSON(), secretFields);
+                        _d.label = 4;
+                    case 4: return [4 /*yield*/, ConfigStatics.updateConfig(safeBody)];
+                    case 5:
                         config = _d.sent();
                         logger_1.logger.info("Configuration updated by ".concat((_c = (_b = req.user) === null || _b === void 0 ? void 0 : _b.email) !== null && _c !== void 0 ? _c : "unknown"));
                         data = redactSecrets(config.toJSON(), secretFields);
-                        return [2 /*return*/, res.json({ data: data })];
+                        if (!this.options.postUpdate) return [3 /*break*/, 7];
+                        return [4 /*yield*/, this.options.postUpdate(data, prevValue, req)];
+                    case 6:
+                        _d.sent();
+                        _d.label = 7;
+                    case 7: return [2 /*return*/, res.json({ data: data })];
                 }
             });
         }); }));
-        // POST /configuration/list-secrets — list secret fields and optionally resolve from provider
-        app.post("".concat(basePath, "/list-secrets"), (0, auth_1.authenticateMiddleware)(), requireAdmin, (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
-            var resolved, updates, resolved_1, resolved_1_1, _a, path, value;
-            var e_3, _b;
-            return __generator(this, function (_c) {
-                switch (_c.label) {
+        // POST /configuration/list-secrets — read-only status of each secret field.
+        // Never resolves values into the document and never returns secret values.
+        var validateSecretsHandler = (0, api_1.asyncHandler)(function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+            var resolved, fields;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
                     case 0: return [4 /*yield*/, ConfigStatics.resolveSecrets()];
                     case 1:
-                        resolved = _c.sent();
-                        if (!(resolved.size > 0)) return [3 /*break*/, 3];
-                        updates = {};
-                        try {
-                            for (resolved_1 = __values(resolved), resolved_1_1 = resolved_1.next(); !resolved_1_1.done; resolved_1_1 = resolved_1.next()) {
-                                _a = __read(resolved_1_1.value, 2), path = _a[0], value = _a[1];
-                                updates[path] = value;
-                            }
-                        }
-                        catch (e_3_1) { e_3 = { error: e_3_1 }; }
-                        finally {
-                            try {
-                                if (resolved_1_1 && !resolved_1_1.done && (_b = resolved_1.return)) _b.call(resolved_1);
-                            }
-                            finally { if (e_3) throw e_3.error; }
-                        }
-                        return [4 /*yield*/, ConfigStatics.updateConfig(updates)];
-                    case 2:
-                        _c.sent();
-                        logger_1.logger.info("Refreshed ".concat(resolved.size, "/").concat(secretFields.length, " secrets"));
-                        _c.label = 3;
-                    case 3: return [2 /*return*/, res.json({
-                            message: "Resolved ".concat(resolved.size, "/").concat(secretFields.length, " secrets."),
-                            resolved: resolved.size,
-                            secretFields: secretFields.map(function (s) { return ({ path: s.path, secretName: s.secretName }); }),
-                            total: secretFields.length,
-                        })];
+                        resolved = _a.sent();
+                        fields = secretFields.map(function (s) { return ({
+                            isConfigured: resolved.has(s.path),
+                            path: s.path,
+                            resolvable: resolved.has(s.path),
+                            secretName: s.secretName,
+                            version: s.version,
+                        }); });
+                        logger_1.logger.info("Validated ".concat(resolved.size, "/").concat(secretFields.length, " secrets (read-only)"));
+                        return [2 /*return*/, res.json({
+                                message: "".concat(resolved.size, "/").concat(secretFields.length, " secrets resolvable."),
+                                resolved: resolved.size,
+                                secretFields: fields,
+                                total: secretFields.length,
+                            })];
                 }
             });
-        }); }));
+        }); });
+        app.post("".concat(basePath, "/list-secrets"), (0, auth_1.authenticateMiddleware)(), this.guardFor("listSecrets", "read"), validateSecretsHandler);
+        // Accurate alias for the read-only validation semantics.
+        app.post("".concat(basePath, "/validate-secrets"), (0, auth_1.authenticateMiddleware)(), this.guardFor("listSecrets", "read"), validateSecretsHandler);
         logger_1.logger.info("Configuration routes mounted at ".concat(basePath));
     };
     /**

package/dist/configurationPlugin.d.ts

@@ -6,13 +6,27 @@ export interface SecretFieldMeta {
     path: string;
     secretProvider?: string;
     secretName: string;
+    /**
+     * Optional secret version to pin resolution to. When omitted the provider
+     * resolves the latest version. Discovered from the `secretVersion` schema
+     * path option.
+     */
+    version?: string;
 }
 /**
  * Interface for adapters that resolve secret values from external providers.
  */
 export interface SecretProvider {
     name: string;
-    getSecret(secretName: string): Promise<string | null>;
+    /**
+     * Resolve a secret value by name. Returns `null` when the secret is not found.
+     *
+     * @param secretName - The secret identifier (short name or provider-specific path).
+     * @param version - Optional version to pin resolution to. Providers that do not
+     *   support versioning (e.g. environment variables) ignore this parameter. When
+     *   omitted, the latest version is resolved.
+     */
+    getSecret(secretName: string, version?: string): Promise<string | null>;
 }
 /**
  * Options passed to configurationPlugin.
@@ -23,6 +37,18 @@ export interface ConfigurationPluginOptions {
      * Typically set during app startup so the model can resolve secrets on demand.
      */
     secretProvider?: SecretProvider;
+    /**
+     * When `true`, adds a `_singleton` sentinel field with a unique index to
+     * enforce the singleton constraint at the database level.
+     *
+     * Defaults to `false`. Leave this off when the consuming app already enforces
+     * a single non-deleted document via the pre-save guard (the default behavior)
+     * or via its own indexes/soft-delete plugin, to avoid double-enforcement and
+     * conflicting indexes.
+     *
+     * @defaultValue false
+     */
+    enforceSingletonIndex?: boolean;
 }
 /**
  * All dot-notation paths for a type T.
@@ -50,14 +76,26 @@ export interface ConfigurationStatics<T extends object> {
     getConfig(): Promise<T & Document>;
     /** Get a specific value by dot-notation key. */
     getConfig<P extends Paths<T>>(key: P): Promise<PathValue<T, P>>;
-    /** Update the singleton configuration document (deep merge). */
+    /**
+     * Update the singleton configuration document.
+     *
+     * The patch is flattened into MongoDB dotted paths and applied with
+     * `findOneAndUpdate({$set})`. This preserves sibling fields inside nested
+     * subdocuments when a partial nested patch is supplied, and tolerates legacy /
+     * out-of-schema fields already persisted on the document (unlike a full
+     * `doc.save()`, which throws under `strict: "throw"`).
+     */
     updateConfig(updates: DeepPartial<T>): Promise<T & Document>;
     /** Get secret field metadata discovered from the schema. */
     getSecretFields(): SecretFieldMeta[];
     /**
      * Resolve all secret field values from a provider.
      * Uses the provider passed here, or falls back to the one configured in the plugin options.
-     * Returns a map of path -> value.
+     * Returns an **in-memory** map of path -> value for programmatic use (startup
+     * self-checks, request-time resolution).
+     *
+     * This method never persists resolved values. Secret material must never be
+     * written to the configuration document.
      */
     resolveSecrets(provider?: SecretProvider): Promise<Map<string, string>>;
 }
@@ -77,17 +115,35 @@ export interface ConfigurationStatics<T extends object> {
  */
 export interface ConfigurationModel<T extends object> extends Model<T>, ConfigurationStatics<T> {
 }
+/**
+ * Flattens a nested patch into MongoDB-style dotted paths, recursing into plain
+ * objects only; arrays and other values are treated as leaves.
+ *
+ * @example
+ * flattenToDotPaths({a: {b: 1}}) // => [["a.b", 1]]
+ */
+export declare const flattenToDotPaths: (obj: Record<string, unknown>, prefix?: string) => Array<[string, unknown]>;
 /**
  * Mongoose schema plugin that adds singleton configuration behavior.
  *
  * Adds:
- * - Pre-save hook enforcing exactly one document
+ * - Pre-save hook enforcing exactly one non-deleted document (soft-delete aware
+ *   when the schema has a `deleted` path, e.g. via `isDeletedPlugin`)
  * - `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
- * - `updateConfig(updates)` static: patches the singleton
+ * - `updateConfig(updates)` static: patches the singleton via `findOneAndUpdate({$set})`
+ *   with dotted paths (preserves sibling subdoc fields; tolerates legacy fields)
  * - `getSecretFields()` static: returns metadata for fields with `secret: true`
- * - `resolveSecrets(provider?)` static: fetches secret values, using the plugin provider by default
+ * - `resolveSecrets(provider?)` static: resolves secret values into an in-memory map,
+ *   using the plugin provider by default (never persists values)
+ * - Hard-delete blockers (`deleteOne`/`deleteMany`/`findOneAndDelete`); soft deletes
+ *   (setting `deleted: true`) are allowed
+ *
+ * Soft deletes are allowed and a soft-deleted document does not block creating a
+ * new singleton. The `_singleton` unique index is opt-in via
+ * `enforceSingletonIndex` (default off).
  *
- * Mark fields as secrets using schema path options:
+ * Mark fields as secrets using schema path options. Pin a version with the
+ * optional `secretVersion` option:
  * ```typescript
  * const configSchema = new Schema({
  *   apiKey: {
@@ -95,6 +151,7 @@ export interface ConfigurationModel<T extends object> extends Model<T>, Configur
  *     description: "Third-party API key",
  *     secret: true,
  *     secretName: "my-api-key",
+ *     secretVersion: "3", // optional — resolves "latest" when omitted
  *   },
  * });
  * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});