@terreno/api 0.13.2 → 0.14.0

package/src/betterAuthSetup.ts

@@ -14,6 +14,7 @@ import type {UserModel} from "./auth";
 import type {BetterAuthConfig, BetterAuthSessionData, BetterAuthUser} from "./betterAuth";
 import {logger} from "./logger";
 import {findOneOrNoneFor} from "./plugins";
+import {updateRequestContextFromRequest} from "./requestContext";
 
 /**
  * The Better Auth instance type.
@@ -23,9 +24,15 @@ export type BetterAuthInstance = ReturnType<typeof betterAuth>;
 /**
  * Options for creating a Better Auth instance.
  */
+// Minimal shape we use from the MongoDB native client returned by mongoose connection
+export interface MongoClientLike {
+  // biome-ignore lint/suspicious/noExplicitAny: the MongoDB driver Db type is opaque to this layer; it is passed straight to better-auth's adapter
+  db: () => any;
+}
+
 export interface CreateBetterAuthOptions {
   config: BetterAuthConfig;
-  mongoClient: any;
+  mongoClient: MongoClientLike;
   userModel?: UserModel;
 }
 
@@ -88,7 +95,7 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
     trustedOrigins: config.trustedOrigins ?? [],
   });
 
-  return auth as any;
+  return auth as BetterAuthInstance;
 };
 
 /**
@@ -108,31 +115,38 @@ export const createBetterAuthSessionMiddleware = (
       if (session?.user && session?.session) {
         const betterAuthUser = session.user as BetterAuthUser;
 
+        const reqWithSession = req as Request & {
+          user?: Request["user"];
+          betterAuthSession?: BetterAuthSessionData;
+        };
         if (userModel) {
           // Look up the application user by betterAuthId
           const appUser = await findOneOrNoneFor(userModel, {
             betterAuthId: betterAuthUser.id,
           });
           if (appUser) {
-            (req as any).user = appUser;
-            (req as any).betterAuthSession = session;
+            reqWithSession.user = appUser as unknown as Request["user"];
+            reqWithSession.betterAuthSession = session as unknown as BetterAuthSessionData;
+            updateRequestContextFromRequest(req);
           } else {
             // User exists in Better Auth but not synced yet - create them
             const newUser = await syncBetterAuthUser(userModel, betterAuthUser);
-            (req as any).user = newUser;
-            (req as any).betterAuthSession = session;
+            reqWithSession.user = newUser as unknown as Request["user"];
+            reqWithSession.betterAuthSession = session as unknown as BetterAuthSessionData;
+            updateRequestContextFromRequest(req);
           }
         } else {
           // No user model - just attach the Better Auth user directly
-          (req as any).user = {
+          reqWithSession.user = {
             _id: betterAuthUser.id,
             admin: false,
             betterAuthId: betterAuthUser.id,
             email: betterAuthUser.email,
             id: betterAuthUser.id,
             name: betterAuthUser.name,
-          };
-          (req as any).betterAuthSession = session;
+          } as unknown as Request["user"];
+          reqWithSession.betterAuthSession = session as unknown as BetterAuthSessionData;
+          updateRequestContextFromRequest(req);
         }
       }
 
@@ -148,15 +162,27 @@ export const createBetterAuthSessionMiddleware = (
  * Syncs a Better Auth user to the application User model.
  * Creates or updates the user as needed.
  */
+// Loose shape used when mutating Mongoose user documents during Better Auth sync.
+// The fields are added by the consumer's user schema (via baseUserPlugin or similar).
+interface MutableUserDoc {
+  email?: string;
+  name?: string;
+  betterAuthId?: string;
+  oauthProvider?: string | null;
+  id?: string;
+  save: () => Promise<unknown>;
+}
+
 export const syncBetterAuthUser = async (
   userModel: UserModel,
   betterAuthUser: BetterAuthUser,
   oauthProvider?: string
+  // biome-ignore lint/suspicious/noExplicitAny: return is a consumer-defined user document; tests inspect varied fields
 ): Promise<any> => {
   try {
-    const existingUser: any = await findOneOrNoneFor(userModel, {
+    const existingUser = (await findOneOrNoneFor(userModel, {
       betterAuthId: betterAuthUser.id,
-    });
+    })) as unknown as MutableUserDoc | null;
 
     if (existingUser) {
       // Update existing user if needed
@@ -169,9 +195,9 @@ export const syncBetterAuthUser = async (
     }
 
     // Check if user exists by email (migration case)
-    const userByEmail: any = await findOneOrNoneFor(userModel, {
+    const userByEmail = (await findOneOrNoneFor(userModel, {
       email: betterAuthUser.email,
-    });
+    })) as unknown as MutableUserDoc | null;
     if (userByEmail) {
       // Link existing user to Better Auth
       userByEmail.betterAuthId = betterAuthUser.id;
@@ -184,14 +210,15 @@ export const syncBetterAuthUser = async (
 
     // Use Better Auth ID as _id when it's a valid ObjectId (MongoDB adapter) so frontend IDs match
     const useAsId = mongoose.isValidObjectId(betterAuthUser.id) ? {_id: betterAuthUser.id} : {};
-    const newUser: any = new (userModel as any)({
+    // biome-ignore lint/suspicious/noExplicitAny: userModel is generic across consumers — constructor args are runtime-validated
+    const newUser = new (userModel as any)({
       ...useAsId,
       admin: false,
       betterAuthId: betterAuthUser.id,
       email: betterAuthUser.email,
       name: betterAuthUser.name || betterAuthUser.email.split("@")[0],
       oauthProvider: oauthProvider || null,
-    });
+    }) as MutableUserDoc;
     await newUser.save();
     logger.info(`Created new user from Better Auth: ${newUser.id}`);
     return newUser;
@@ -222,9 +249,9 @@ export const mountBetterAuthRoutes = (
 /**
  * Gets the MongoDB client from the mongoose connection.
  */
-export const getMongoClientFromMongoose = (): any => {
+export const getMongoClientFromMongoose = (): MongoClientLike => {
   const connection = mongoose.connection;
-  const client = (connection as any).client;
+  const client = (connection as unknown as {client?: MongoClientLike}).client;
   if (!client) {
     throw new Error("Mongoose is not connected. Ensure MongoDB connection is established first.");
   }
@@ -249,12 +276,12 @@ export const setupBetterAuthUserSync = (_auth: BetterAuthInstance, _userModel: U
  * Extracts Better Auth session data from the request.
  */
 export const getBetterAuthSession = (req: Request): BetterAuthSessionData | null => {
-  return (req as any).betterAuthSession ?? null;
+  return (req as Request & {betterAuthSession?: BetterAuthSessionData}).betterAuthSession ?? null;
 };
 
 /**
  * Checks if the request has a valid Better Auth session.
  */
 export const hasBetterAuthSession = (req: Request): boolean => {
-  return Boolean((req as any).betterAuthSession);
+  return Boolean((req as Request & {betterAuthSession?: BetterAuthSessionData}).betterAuthSession);
 };

package/src/config.test.ts

@@ -0,0 +1,255 @@
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+
+import {Config} from "./config";
+
+const KEYS = [
+  "TERRENO_CFG_STRING",
+  "TERRENO_CFG_DEFAULTED",
+  "TERRENO_CFG_NUM",
+  "TERRENO_CFG_BOOL",
+  "TERRENO_CFG_JSON",
+  "TERRENO_CFG_UNDEFAULTED",
+  "TERRENO_CFG_UNREGISTERED",
+];
+
+const resetEnv = (): void => {
+  for (const key of KEYS) {
+    Reflect.deleteProperty(process.env, key);
+  }
+};
+
+describe("Config", () => {
+  beforeEach(() => {
+    Config.clearRegistryForTesting();
+    Config.clearOverrides();
+    Config.setCachedEnv(null);
+    Config.setEnvLoader(null);
+    resetEnv();
+
+    Config.register("TERRENO_CFG_STRING");
+    Config.register("TERRENO_CFG_DEFAULTED", {default: "fallback"});
+    Config.register("TERRENO_CFG_NUM", {default: "1000"});
+    Config.register("TERRENO_CFG_BOOL", {default: "false"});
+    Config.register("TERRENO_CFG_JSON", {default: "{}"});
+    Config.register("TERRENO_CFG_UNDEFAULTED");
+  });
+
+  afterEach(() => {
+    resetEnv();
+    Config.clearRegistryForTesting();
+    Config.clearOverrides();
+    Config.setCachedEnv(null);
+    Config.setEnvLoader(null);
+  });
+
+  describe("resolution order", () => {
+    it("returns the registered default when nothing is set", () => {
+      expect(Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+    });
+
+    it("returns process.env when set and no cache/override is present", () => {
+      process.env.TERRENO_CFG_STRING = "fromEnv";
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("fromEnv");
+    });
+
+    it("cache wins over process.env", () => {
+      process.env.TERRENO_CFG_STRING = "fromEnv";
+      Config.setCachedEnv({TERRENO_CFG_STRING: "fromCache"});
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("fromCache");
+    });
+
+    it("override wins over cache and process.env", () => {
+      process.env.TERRENO_CFG_STRING = "fromEnv";
+      Config.setCachedEnv({TERRENO_CFG_STRING: "fromCache"});
+      Config.setOverride("TERRENO_CFG_STRING", "fromOverride");
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("fromOverride");
+    });
+
+    it("falls through empty-string cache values to process.env", () => {
+      process.env.TERRENO_CFG_STRING = "fromEnv";
+      Config.setCachedEnv({TERRENO_CFG_STRING: ""});
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("fromEnv");
+    });
+
+    it("falls through empty-string process.env to default", () => {
+      process.env.TERRENO_CFG_DEFAULTED = "";
+      expect(Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+    });
+
+    it("returns undefined for an unregistered key with nothing set", () => {
+      expect(Config.get("TERRENO_CFG_UNREGISTERED")).toBeUndefined();
+    });
+
+    it("returns process.env for an unregistered key when set", () => {
+      process.env.TERRENO_CFG_UNREGISTERED = "value";
+      expect(Config.get("TERRENO_CFG_UNREGISTERED")).toBe("value");
+    });
+
+    it("setOverride(key, undefined) is treated as 'force unset'", () => {
+      process.env.TERRENO_CFG_STRING = "fromEnv";
+      Config.setOverride("TERRENO_CFG_STRING", undefined);
+      expect(Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+    });
+  });
+
+  describe("getNumber", () => {
+    it("parses numeric process.env values", () => {
+      process.env.TERRENO_CFG_NUM = "5000";
+      expect(Config.getNumber("TERRENO_CFG_NUM")).toBe(5000);
+    });
+
+    it("parses the registered default", () => {
+      expect(Config.getNumber("TERRENO_CFG_NUM")).toBe(1000);
+    });
+
+    it("returns undefined when no value is available", () => {
+      expect(Config.getNumber("TERRENO_CFG_UNDEFAULTED")).toBeUndefined();
+    });
+
+    it("throws on non-numeric values", () => {
+      process.env.TERRENO_CFG_NUM = "not-a-number";
+      expect(() => Config.getNumber("TERRENO_CFG_NUM")).toThrow(/not a valid number/);
+    });
+
+    it("throws on partially-numeric strings like '5000ms'", () => {
+      process.env.TERRENO_CFG_NUM = "5000ms";
+      expect(() => Config.getNumber("TERRENO_CFG_NUM")).toThrow(/not a valid number/);
+    });
+
+    it("supports floats", () => {
+      process.env.TERRENO_CFG_NUM = "3.14";
+      expect(Config.getNumber("TERRENO_CFG_NUM")).toBe(3.14);
+    });
+  });
+
+  describe("getBoolean", () => {
+    it("returns true for 'true'", () => {
+      process.env.TERRENO_CFG_BOOL = "true";
+      expect(Config.getBoolean("TERRENO_CFG_BOOL")).toBe(true);
+    });
+
+    it("returns true for 'TRUE' (case-insensitive)", () => {
+      process.env.TERRENO_CFG_BOOL = "TRUE";
+      expect(Config.getBoolean("TERRENO_CFG_BOOL")).toBe(true);
+    });
+
+    it("returns false for 'false'", () => {
+      process.env.TERRENO_CFG_BOOL = "false";
+      expect(Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+    });
+
+    it("returns false when unset and default is 'false'", () => {
+      expect(Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+    });
+
+    it("returns false for any non-true string", () => {
+      process.env.TERRENO_CFG_BOOL = "yes";
+      expect(Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+    });
+  });
+
+  describe("getJSON", () => {
+    it("parses valid JSON", () => {
+      process.env.TERRENO_CFG_JSON = JSON.stringify({hook: "https://example.com"});
+      expect(Config.getJSON<Record<string, string>>("TERRENO_CFG_JSON")).toEqual({
+        hook: "https://example.com",
+      });
+    });
+
+    it("parses the registered default", () => {
+      expect(Config.getJSON<Record<string, unknown>>("TERRENO_CFG_JSON")).toEqual({});
+    });
+
+    it("returns undefined when nothing is set and no default exists", () => {
+      expect(Config.getJSON("TERRENO_CFG_UNDEFAULTED")).toBeUndefined();
+    });
+
+    it("throws on malformed JSON instead of silently returning undefined", () => {
+      process.env.TERRENO_CFG_JSON = "{not json";
+      expect(() => Config.getJSON("TERRENO_CFG_JSON")).toThrow(/not valid JSON/);
+    });
+  });
+
+  describe("registry", () => {
+    it("exposes registered keys in sorted order", () => {
+      const keys = Config.getRegisteredKeys();
+      const sorted = [...keys].sort();
+      expect(keys).toEqual(sorted);
+    });
+
+    it("isRegistered returns true for known keys", () => {
+      expect(Config.isRegistered("TERRENO_CFG_STRING")).toBe(true);
+    });
+
+    it("isRegistered returns false for unknown keys", () => {
+      expect(Config.isRegistered("NOT_A_REAL_KEY")).toBe(false);
+    });
+
+    it("getDefault returns the registered default", () => {
+      expect(Config.getDefault("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+    });
+
+    it("getDefault returns undefined for keys with no default", () => {
+      expect(Config.getDefault("TERRENO_CFG_STRING")).toBeUndefined();
+    });
+
+    it("getRegistration exposes secret + description metadata", () => {
+      Config.register("TERRENO_CFG_WITH_META", {
+        description: "A secret thing",
+        secret: true,
+      });
+      const meta = Config.getRegistration("TERRENO_CFG_WITH_META");
+      expect(meta?.secret).toBe(true);
+      expect(meta?.description).toBe("A secret thing");
+    });
+
+    it("re-registering the same key throws", () => {
+      expect(() => Config.register("TERRENO_CFG_STRING")).toThrow(/registered more than once/);
+    });
+
+    it("does not treat Object prototype keys as registered", () => {
+      expect(Config.isRegistered("constructor")).toBe(false);
+      expect(Config.isRegistered("toString")).toBe(false);
+      expect(Config.isRegistered("hasOwnProperty")).toBe(false);
+      // And re-registering one of these names should still succeed.
+      expect(() => Config.register("toString", {default: "x"})).not.toThrow();
+      expect(Config.get("toString")).toBe("x");
+    });
+  });
+
+  describe("clearOverrides", () => {
+    it("removes all overrides", () => {
+      Config.setOverride("TERRENO_CFG_STRING", "x");
+      Config.setOverride("TERRENO_CFG_DEFAULTED", "y");
+      Config.clearOverrides();
+      expect(Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+      expect(Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+    });
+  });
+
+  describe("refresh", () => {
+    it("loads values via the registered env loader", async () => {
+      Config.setEnvLoader(async () => ({TERRENO_CFG_STRING: "fromLoader"}));
+      await Config.refresh();
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("fromLoader");
+    });
+
+    it("clears the cache when no loader is registered", async () => {
+      Config.setCachedEnv({TERRENO_CFG_STRING: "stale"});
+      Config.setEnvLoader(null);
+      await Config.refresh();
+      expect(Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+    });
+
+    it("updates the cache on each refresh", async () => {
+      let payload: Record<string, string> = {TERRENO_CFG_STRING: "first"};
+      Config.setEnvLoader(async () => payload);
+      await Config.refresh();
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("first");
+
+      payload = {TERRENO_CFG_STRING: "second"};
+      await Config.refresh();
+      expect(Config.get("TERRENO_CFG_STRING")).toBe("second");
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,206 @@
+/**
+ * Runtime configuration registry with a fixed resolution order:
+ *
+ *   1. In-process override (Config.setOverride) — highest, for tests/bootstrap
+ *   2. Cached env map — typically loaded from an admin-editable Mongoose document
+ *   3. process.env
+ *   4. Registered default
+ *
+ * Why a registry: every key migrating off raw `process.env` declares its type
+ * and default in one place. That keeps the admin UI honest (no surprise keys),
+ * gives synchronous access without scattered `?? "default"` literals at call
+ * sites, and lets tests assert behavior against a single source of truth.
+ *
+ * Why sync: hundreds of call sites read configuration during request handling
+ * and module init; an async API would force enormous refactors. Callers load
+ * the env map once via `Config.refresh()` after Mongo connects, then read
+ * synchronously from cache.
+ *
+ * The mechanism is agnostic to where the env map comes from. Apps wire up
+ * their backing store with `Config.setEnvLoader(fn)`. The optional
+ * `envConfigurationPlugin` provides a drop-in Mongoose schema integration.
+ */
+
+const overrides = new Map<string, string | undefined>();
+
+let cachedEnv: Record<string, string> | null = null;
+
+let envLoader: (() => Promise<Record<string, string>>) | null = null;
+
+export interface ConfigRegistration {
+  /** Default returned when neither override, cache, nor process.env supplies a value. */
+  default?: string;
+  /** Documentation surfaced in the admin UI. */
+  description?: string;
+  /** Marks the key as a secret so admin UI can mask the value. */
+  secret?: boolean;
+}
+
+// Null-prototype object so lookups don't resolve inherited keys like
+// `constructor` / `toString` as accidentally-registered entries.
+const REGISTRY: Record<string, ConfigRegistration> = Object.create(null);
+
+/**
+ * Registers a configuration key, its default, and metadata. Re-registration
+ * of the same key throws so duplicates surface at boot.
+ */
+const register = (key: string, registration: ConfigRegistration = {}): void => {
+  if (REGISTRY[key]) {
+    throw new Error(`Config key "${key}" registered more than once`);
+  }
+  REGISTRY[key] = registration;
+};
+
+/**
+ * Returns the configured string value for `key`, applying the resolution
+ * order documented at the top of this file. Returns `undefined` if no
+ * source supplies a value and no default was registered.
+ */
+const getString = (key: string): string | undefined => {
+  if (overrides.has(key)) {
+    return overrides.get(key);
+  }
+  if (cachedEnv && key in cachedEnv) {
+    const v = cachedEnv[key];
+    if (v !== undefined && v !== "") {
+      return v;
+    }
+  }
+  // Guard against process.env keys like "toString" / "constructor" inheriting
+  // a function from Object.prototype. Only accept string values.
+  const fromProcess = process.env[key];
+  if (typeof fromProcess === "string" && fromProcess !== "") {
+    return fromProcess;
+  }
+  return REGISTRY[key]?.default;
+};
+
+/**
+ * Returns the configured value as a number. Throws if a value is present but
+ * not finite — silent NaN propagation has bitten apps before.
+ */
+const getNumber = (key: string): number | undefined => {
+  const raw = getString(key);
+  if (raw === undefined) {
+    return undefined;
+  }
+  // Number() rejects partially-numeric strings like "5000ms" (returns NaN)
+  // whereas parseFloat would silently truncate to 5000.
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Config key "${key}" is not a valid number: ${JSON.stringify(raw)}`);
+  }
+  return parsed;
+};
+
+/**
+ * Returns true iff the string value equals "true" (case-insensitive). Mirrors
+ * the existing `process.env.X === "true"` idiom.
+ */
+const getBoolean = (key: string): boolean => {
+  const raw = getString(key);
+  return raw !== undefined && raw.toLowerCase() === "true";
+};
+
+/**
+ * Parses a JSON-encoded config value. Returns undefined if unset; throws on
+ * malformed JSON so misconfiguration fails loud at the call site rather than
+ * producing silent runtime errors later.
+ */
+const getJSON = <T = unknown>(key: string): T | undefined => {
+  const raw = getString(key);
+  if (raw === undefined) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch (error) {
+    throw new Error(`Config key "${key}" is not valid JSON: ${(error as Error).message}`);
+  }
+};
+
+/**
+ * Registers a loader that returns the env map (typically backed by an
+ * admin-editable Mongoose document). Called once at app startup before
+ * the first `Config.refresh()`.
+ */
+const setEnvLoader = (loader: (() => Promise<Record<string, string>>) | null): void => {
+  envLoader = loader;
+};
+
+/**
+ * Reloads the in-memory cache by invoking the registered env loader. No-op
+ * (clears cache) if no loader has been registered.
+ */
+const refresh = async (): Promise<void> => {
+  if (!envLoader) {
+    cachedEnv = {};
+    return;
+  }
+  cachedEnv = await envLoader();
+};
+
+/** Replaces the cache directly. Intended for the envConfigurationPlugin and tests. */
+const setCachedEnv = (env: Record<string, string> | null): void => {
+  cachedEnv = env;
+};
+
+/**
+ * Sets an in-process override for `key`. Highest precedence — wins over
+ * the cached env map. Intended for tests and bootstrap helpers.
+ */
+const setOverride = (key: string, value: string | undefined): void => {
+  overrides.set(key, value);
+};
+
+/** Clears every override. Call from afterEach in tests. */
+const clearOverrides = (): void => {
+  overrides.clear();
+};
+
+/** Returns the registered default (if any) for `key`. */
+const getDefault = (key: string): string | undefined => {
+  return REGISTRY[key]?.default;
+};
+
+/** Returns the registration metadata for `key`, including secret/description. */
+const getRegistration = (key: string): ConfigRegistration | undefined => {
+  return REGISTRY[key];
+};
+
+/** Returns the registered keys, sorted. Used by the admin UI. */
+const getRegisteredKeys = (): string[] => {
+  return Object.keys(REGISTRY).sort();
+};
+
+/** Returns true if `key` was registered. */
+const isRegistered = (key: string): boolean => {
+  return key in REGISTRY;
+};
+
+/** Removes every registered key. Intended for tests. */
+const clearRegistryForTesting = (): void => {
+  for (const key of Object.keys(REGISTRY)) {
+    delete REGISTRY[key];
+  }
+};
+
+export const Config = {
+  clearOverrides,
+  clearRegistryForTesting,
+  get: getString,
+  getBoolean,
+  getDefault,
+  getJSON,
+  getNumber,
+  getRegisteredKeys,
+  getRegistration,
+  isRegistered,
+  refresh,
+  register,
+  setCachedEnv,
+  setEnvLoader,
+  setOverride,
+};
+
+export type ConfigType = typeof Config;

package/src/configuration.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {beforeEach, describe, expect, it} from "bun:test";
 import type express from "express";
 import mongoose, {Schema} from "mongoose";