@terreno/api 0.3.1 → 0.4.0

package/src/configurationPlugin.ts

@@ -0,0 +1,288 @@
+import type {Document, Model, Schema} from "mongoose";
+
+import {APIError} from "./errors";
+import {logger} from "./logger";
+
+/**
+ * Metadata for a secret field discovered by the configuration plugin.
+ */
+export interface SecretFieldMeta {
+  path: string;
+  secretProvider?: string;
+  secretName: string;
+}
+
+/**
+ * Interface for adapters that resolve secret values from external providers.
+ */
+export interface SecretProvider {
+  name: string;
+  getSecret(secretName: string): Promise<string | null>;
+}
+
+/**
+ * Options passed to configurationPlugin.
+ */
+export interface ConfigurationPluginOptions {
+  /**
+   * Secret provider used when resolveSecrets() is called without an explicit provider.
+   * Typically set during app startup so the model can resolve secrets on demand.
+   */
+  secretProvider?: SecretProvider;
+}
+
+// ---------------------------------------------------------------------------
+// Path type utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * All dot-notation paths for a type T.
+ * @example Paths<{a: {b: string}; c: number}> = "a" | "a.b" | "c"
+ */
+export type Paths<T extends object> = {
+  [K in keyof T & string]: T[K] extends object ? K | `${K}.${Paths<T[K]>}` : K;
+}[keyof T & string];
+
+/**
+ * The value type at a dot-notation path P within type T.
+ * @example PathValue<{a: {b: string}}, "a.b"> = string
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof T
+    ? PathValue<NonNullable<T[K]>, Rest>
+    : never
+  : P extends keyof T
+    ? T[P]
+    : never;
+
+/**
+ * Deeply partial version of T, for use in updateConfig.
+ */
+export type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+// ---------------------------------------------------------------------------
+// Statics interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Static methods added by configurationPlugin to the Mongoose model.
+ */
+export interface ConfigurationStatics<T extends object> {
+  /** Get the full singleton configuration document. */
+  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). */
+  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.
+   */
+  resolveSecrets(provider?: SecretProvider): Promise<Map<string, string>>;
+}
+
+/**
+ * Convenience type for a Mongoose model with configurationPlugin applied.
+ *
+ * Use this when declaring your configuration model to get full type safety:
+ * ```typescript
+ * export const AppConfig = mongoose.model<AppConfigDocument, ConfigurationModel<AppConfigDocument>>(
+ *   "AppConfig",
+ *   appConfigSchema,
+ * );
+ * // Then call:
+ * const name = await AppConfig.getConfig("general.appName"); // typed as string
+ * const full = await AppConfig.getConfig(); // typed as AppConfigDocument
+ * ```
+ */
+export type ConfigurationModel<T extends object> = Model<T> & ConfigurationStatics<T>;
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * Mongoose schema plugin that adds singleton configuration behavior.
+ *
+ * Adds:
+ * - Pre-save hook enforcing exactly one document
+ * - `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
+ * - `updateConfig(updates)` static: patches the singleton
+ * - `getSecretFields()` static: returns metadata for fields with `secret: true`
+ * - `resolveSecrets(provider?)` static: fetches secret values, using the plugin provider by default
+ *
+ * Mark fields as secrets using schema path options:
+ * ```typescript
+ * const configSchema = new Schema({
+ *   apiKey: {
+ *     type: String,
+ *     description: "Third-party API key",
+ *     secret: true,
+ *     secretName: "my-api-key",
+ *   },
+ * });
+ * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
+ * ```
+ */
+export const configurationPlugin = (schema: Schema, options?: ConfigurationPluginOptions): void => {
+  const pluginOptions = options ?? {};
+
+  // Add a sentinel field with a unique index to enforce singleton at the DB level.
+  // All config documents get _singleton: "config", and the unique index prevents duplicates.
+  schema.add({
+    _singleton: {default: "config", immutable: true, select: false, type: String},
+  });
+  schema.index({_singleton: 1}, {unique: true});
+
+  // Enforce singleton: only one document allowed (application-level guard)
+  schema.pre("save", async function () {
+    if (this.isNew) {
+      // Intentional unfiltered findOne — checking if any singleton document exists
+      const existing = await (this.constructor as Model<unknown>).findOne({});
+      if (existing) {
+        throw new APIError({
+          status: 409,
+          title: "Only one configuration document is allowed. Use updateConfig() instead.",
+        });
+      }
+    }
+  });
+
+  // Prevent hard deletion of the singleton (soft deletes via isDeletedPlugin still work)
+  const createHardDeleteError = (): APIError =>
+    new APIError({
+      status: 400,
+      title:
+        "Cannot hard-delete the configuration document. Use updateConfig() or soft delete instead.",
+    });
+
+  schema.pre("deleteOne", {document: true, query: true}, () => {
+    throw createHardDeleteError();
+  });
+  schema.pre("deleteMany", () => {
+    throw createHardDeleteError();
+  });
+  schema.pre("findOneAndDelete", () => {
+    throw createHardDeleteError();
+  });
+
+  // Static: get the singleton configuration document or a value at a path (race-safe via upsert)
+  schema.statics.getConfig = async function (key?: string): Promise<unknown> {
+    let config = await this.findOne({});
+    if (!config) {
+      try {
+        // Use `new` + `save` instead of `create({})` so Mongoose initializes
+        // nested subdocument defaults (create({}) skips them).
+        config = new this();
+        await config.save();
+      } catch (err: unknown) {
+        // If another process created the document between findOne and create,
+        // the pre-save hook will throw a 409. Just fetch the existing one.
+        if ((err as {status?: number})?.status === 409) {
+          config = await this.findOne({});
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    if (key === undefined) {
+      return config;
+    }
+
+    // Resolve dot-notation key into the document
+    const parts = key.split(".");
+    let value: unknown = config.toObject();
+    for (const part of parts) {
+      if (value == null || typeof value !== "object") {
+        return undefined;
+      }
+      value = (value as Record<string, unknown>)[part];
+    }
+    return value;
+  };
+
+  // Static: update the singleton configuration document (race-safe)
+  schema.statics.updateConfig = async function (
+    updates: Record<string, unknown>
+  ): Promise<unknown> {
+    const config = await (this as ConfigurationModel<Record<string, unknown>>).getConfig();
+    Object.assign(config, updates);
+    await (config as Document).save();
+    return config;
+  };
+
+  // Static: discover secret fields from schema options
+  schema.statics.getSecretFields = function (): SecretFieldMeta[] {
+    const secrets: SecretFieldMeta[] = [];
+    const discoverSecrets = (s: Schema, prefix: string) => {
+      s.eachPath((pathName, schemaType) => {
+        const opts = schemaType.options as Record<string, unknown>;
+        if (opts?.secret === true) {
+          secrets.push({
+            path: prefix ? `${prefix}.${pathName}` : pathName,
+            secretName: (opts.secretName as string) ?? pathName,
+            secretProvider: opts.secretProvider as string | undefined,
+          });
+        }
+        // Recurse into subschemas
+        if ((schemaType as {schema?: Schema}).schema) {
+          discoverSecrets(
+            (schemaType as {schema: Schema}).schema,
+            prefix ? `${prefix}.${pathName}` : pathName
+          );
+        }
+      });
+    };
+    discoverSecrets(this.schema, "");
+    return secrets;
+  };
+
+  // Static: resolve secret values from a provider
+  schema.statics.resolveSecrets = async function (
+    provider?: SecretProvider
+  ): Promise<Map<string, string>> {
+    const resolvedProvider = provider ?? pluginOptions.secretProvider;
+    if (!resolvedProvider) {
+      logger.warn(
+        "resolveSecrets called with no provider. Pass a SecretProvider to resolveSecrets() or configurationPlugin options."
+      );
+      return new Map();
+    }
+
+    const secrets = (this as ConfigurationModel<Record<string, unknown>>).getSecretFields();
+    const resolved = new Map<string, string>();
+
+    const results = await Promise.allSettled(
+      secrets.map(async (meta: SecretFieldMeta) => {
+        const value = await resolvedProvider.getSecret(meta.secretName);
+        if (value !== null) {
+          resolved.set(meta.path, value);
+        }
+      })
+    );
+
+    let failCount = 0;
+    for (const result of results) {
+      if (result.status === "rejected") {
+        failCount++;
+        logger.error(`Failed to resolve secret: ${result.reason}`);
+      }
+    }
+
+    if (failCount > 0) {
+      logger.warn(`${failCount}/${secrets.length} secrets failed to resolve`);
+    } else if (secrets.length > 0) {
+      logger.info(
+        `Resolved ${resolved.size}/${secrets.length} secrets from ${resolvedProvider.name}`
+      );
+    }
+
+    return resolved;
+  };
+};

package/src/example.ts

@@ -54,7 +54,7 @@ const FoodModel = model<Food>("Food", schema);
 function getBaseServer() {
   const app = express();
 
-  app.all("/*", (req, res, next) => {
+  app.use((req, res, next) => {
     res.header("Access-Control-Allow-Origin", "*");
     res.header("Access-Control-Allow-Headers", "*");
     // intercepts OPTIONS method

package/src/expressServer.ts

@@ -15,6 +15,7 @@ import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
 import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
 import {sendToSlack} from "./notifiers";
+import {openApiCompatMiddleware, patchAppUse} from "./openApiCompat";
 import {openApiEtagMiddleware} from "./openApiEtag";
 
 const SLOW_READ_MAX = 200;
@@ -180,6 +181,9 @@ function initializeRoutes(
 ): express.Application {
   const app = express();
 
+  // Record mount paths on layers for Express 5 → OpenAPI compat
+  patchAppUse(app);
+
   // TODO: Log a warning when we hit the array limit.
   app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: options.arrayLimit ?? 200}));
 
@@ -210,7 +214,7 @@ function initializeRoutes(
   });
 
   // Add Sentry scopes for session, transaction, and userId if any are set
-  app.all("*", (req: any, _res: any, next: any) => {
+  app.use((req: any, _res: any, next: any) => {
     const transactionId = req.header("X-Transaction-ID");
     const sessionId = req.header("X-Session-ID");
     if (transactionId) {
@@ -226,6 +230,7 @@ function initializeRoutes(
   });
 
   // Add ETag middleware for OpenAPI JSON endpoint before the openapi middleware
+  app.use(openApiCompatMiddleware);
   app.use(openApiEtagMiddleware);
 
   const oapi = openapi({

package/src/githubAuth.ts

@@ -79,7 +79,7 @@ export function setupGitHubAuth(
 
   passport.use(
     "github",
-    new GitHubStrategy(
+    new (GitHubStrategy as any)(
       {
         callbackURL: githubOptions.callbackURL,
         clientID: githubOptions.clientId,
@@ -87,8 +87,8 @@ export function setupGitHubAuth(
         passReqToCallback: true,
         scope,
       },
-      async (
-        req: express.Request,
+      (async (
+        req: any,
         accessToken: string,
         refreshToken: string,
         profile: Profile,
@@ -192,7 +192,7 @@ export function setupGitHubAuth(
           logger.error(`GitHub auth error: ${error}`);
           return done(error);
         }
-      }
+      }) as any
     ) as passport.Strategy
   );
 }

package/src/index.ts

@@ -3,6 +3,8 @@ export * from "./auth";
 export * from "./betterAuth";
 export * from "./betterAuthApp";
 export * from "./betterAuthSetup";
+export * from "./configurationApp";
+export * from "./configurationPlugin";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
@@ -10,11 +12,14 @@ export * from "./logger";
 export * from "./middleware";
 export * from "./notifiers";
 export * from "./openApiBuilder";
+export * from "./openApiCompat";
 export * from "./openApiEtag";
 export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./scriptRunner";
+export * from "./secretProviders";
 export * from "./terrenoApp";
 export * from "./terrenoPlugin";
 export * from "./transformers";

package/src/openApiCompat.ts

@@ -0,0 +1,147 @@
+/**
+ * Patches the Express router stack to add `.regexp` on layers for
+ * compatibility with @wesleytodd/openapi, which expects Express 4-style
+ * layers with `.regexp.fast_slash`.
+ *
+ * In Express 5 (router@2.x), layers use `.slash` (boolean) and `.matchers`
+ * (array of functions) instead of `.regexp`.
+ *
+ * @see https://github.com/wesleytodd/express-openapi/issues/70
+ */
+
+const MOUNT_PATH_KEY = "__openApiMountPath";
+
+/**
+ * Extract Express 4-style keys from a path string.
+ * Parses `:paramName` and `*paramName` segments into `{name, optional}` objects
+ * that @wesleytodd/openapi expects.
+ */
+const extractKeysFromPath = (path: string): Array<{name: string; optional: boolean}> => {
+  const keys: Array<{name: string; optional: boolean}> = [];
+  const paramRegex = /[:*](\w+)\??/g;
+  let match: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: standard regex exec loop
+  while ((match = paramRegex.exec(path)) !== null) {
+    keys.push({name: match[1], optional: match[0].endsWith("?")});
+  }
+  return keys;
+};
+
+/**
+ * Build an Express 4-style regexp from a path string for the openapi parser.
+ *
+ * For paths without params (e.g., `/food`), produces a simple escaped regexp
+ * that the `split()` function in @wesleytodd/openapi can parse directly.
+ *
+ * For paths with `:params` (e.g., `/food/:id`), replaces each param with the
+ * Express 4-style capture group `(?:([^\/]+?))` so that `processComplexMatch()`
+ * in the openapi library can map them to `{paramName}` using `layer.keys`.
+ */
+const buildRegexpForPath = (pathStr: string, isMount: boolean): RegExp => {
+  // Replace :param segments with Express 4-style capture groups, then escape the rest
+  const parts = pathStr.split("/").map((segment) => {
+    if (segment.startsWith(":")) {
+      return "(?:([^\\/]+?))";
+    }
+    return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  const pattern = parts.join("\\/");
+  if (isMount) {
+    return new RegExp(`^${pattern}\\/?(?=\\/|$)`);
+  }
+  return new RegExp(`^${pattern}\\/?$`);
+};
+
+const patchRouterStack = (stack: any[]): void => {
+  for (const layer of stack) {
+    if (layer.regexp !== undefined) {
+      continue;
+    }
+
+    // Determine the path string for this layer
+    let pathStr: string | undefined;
+    const isMount = layer.name === "router" || !!layer.handle?.stack;
+
+    if (layer.slash) {
+      // Express 5 layers use .slash instead of .regexp.fast_slash
+      layer.regexp = {fast_slash: true};
+    } else if (layer[MOUNT_PATH_KEY]) {
+      pathStr = layer[MOUNT_PATH_KEY] as string;
+      layer.regexp = buildRegexpForPath(pathStr, isMount);
+    } else if (layer.path && typeof layer.path === "string") {
+      pathStr = layer.path as string;
+      layer.regexp = buildRegexpForPath(pathStr, false);
+    } else if (layer.route?.path && typeof layer.route.path === "string") {
+      pathStr = layer.route.path as string;
+      layer.regexp = buildRegexpForPath(pathStr, false);
+    } else {
+      layer.regexp = /^\/?$/;
+    }
+
+    // Populate keys in Express 4 format: [{name, optional}]
+    // @wesleytodd/openapi reads layer.keys[i].name for path parameters
+    if (!layer.keys || (Array.isArray(layer.keys) && layer.keys.length === 0)) {
+      if (pathStr) {
+        layer.keys = extractKeysFromPath(pathStr);
+      } else {
+        layer.keys = [];
+      }
+    } else if (Array.isArray(layer.keys) && typeof layer.keys[0] === "string") {
+      // Express 5 stores keys as plain strings after match() — convert to objects
+      layer.keys = layer.keys.map((k: string) => ({name: k, optional: false}));
+    }
+
+    // Recursively patch nested stacks
+    if (layer.handle?.stack) {
+      patchRouterStack(layer.handle.stack);
+    }
+    if (layer.route?.stack) {
+      patchRouterStack(layer.route.stack);
+    }
+  }
+};
+
+/**
+ * Wraps an Express app's `use` method to record the mount path on each
+ * layer added to the router stack. This runs at setup time so that
+ * `patchRouterStack` can read the original path later.
+ *
+ * Must be called before any routes are registered.
+ */
+export const patchAppUse = (app: any): void => {
+  const originalUse = app.use.bind(app);
+  app.use = function patchedUse(...args: any[]) {
+    // Track stack length before the call
+    const router = app._router || app.router;
+    const stackBefore = router?.stack?.length ?? 0;
+
+    const result = originalUse(...args);
+
+    // After use(), check if new layers were added and annotate them
+    const routerAfter = app._router || app.router;
+    if (routerAfter?.stack) {
+      const stackAfter = routerAfter.stack.length;
+      // The first arg is the mount path if it's a string
+      const mountPath = typeof args[0] === "string" ? args[0] : undefined;
+      if (mountPath && mountPath !== "/") {
+        for (let i = stackBefore; i < stackAfter; i++) {
+          routerAfter.stack[i][MOUNT_PATH_KEY] = mountPath.replace(/\/+$/, "");
+        }
+      }
+    }
+
+    return result;
+  };
+};
+
+/**
+ * Express middleware that patches the router stack before OpenAPI doc
+ * generation. Must be mounted before the openapi middleware.
+ */
+export const openApiCompatMiddleware = (req: any, _res: any, next: () => void): void => {
+  const router = req.app._router || req.app.router;
+  if (router?.stack) {
+    patchRouterStack(router.stack);
+  }
+  next();
+};

package/src/permissions.ts

@@ -160,7 +160,7 @@ export function permissionMiddleware<T>(
       if (!data) {
         // Check if document exists but is hidden. Completely skip plugins.
         const hiddenDoc = await model.collection.findOne({
-          _id: new mongoose.Types.ObjectId(req.params.id),
+          _id: new mongoose.Types.ObjectId(req.params.id as string),
         });
 
         if (!hiddenDoc) {