@bhooai/nexus-core 2.0.17 → 2.0.19

package/src/config/ConfigLoader.ts

@@ -47,6 +47,23 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
     merged = deepMerge(merged, defaultConfig);
   }
 
+  // 1c. project identity — resolve `app.name` from every higher layer, then
+  //     derive auth identity, redis prefix and mail `from` from it. This layer
+  //     sits above the framework default but below the user config, so an
+  //     explicit value anywhere in nexus.config.ts / runtime.json / env still
+  //     wins while a project only has to declare its name once.
+  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
+  const runtime = readRuntimeObject(runtimePath);
+  const envLayer = configFromEnv(env);
+  const appName = resolveAppName({
+    userConfig: opts.userConfig,
+    runtime,
+    env: envLayer,
+    cli: opts.cli,
+    root,
+  });
+  merged = deepMerge(merged, deriveAppIdentity(appName));
+
   // 2. user config (nexus.config.ts / nexus.config.js)
   let userConfig = opts.userConfig;
   if (!userConfig && opts.userConfigPath) {
@@ -55,18 +72,10 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   if (userConfig) merged = deepMerge(merged, userConfig);
 
   // 3. runtime.json (admin write-back, gitignored)
-  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
-  if (existsSync(runtimePath)) {
-    try {
-      const runtime = JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
-      merged = deepMerge(merged, runtime);
-    } catch {
-      // A corrupt runtime file must not crash boot; ignore it.
-    }
-  }
+  if (runtime) merged = deepMerge(merged, runtime);
 
   // 4. env
-  merged = deepMerge(merged, configFromEnv(env));
+  merged = deepMerge(merged, envLayer);
 
   // 5. cli flags (highest)
   if (opts.cli) merged = deepMerge(merged, opts.cli);
@@ -76,6 +85,65 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   return Object.freeze(parsed) as NexusConfig;
 }
 
+/** Read nexus.runtime.json (DeepPartial) or an empty object when absent/corrupt. */
+function readRuntimeObject(runtimePath: string): DeepPartial<NexusConfig> {
+  if (!existsSync(runtimePath)) return {};
+  try {
+    return JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
+  } catch {
+    // A corrupt runtime file must not crash boot; ignore it.
+    return {};
+  }
+}
+
+/**
+ * Resolve the project slug used to derive identity/namespaces: an explicit
+ * `app.name` from the highest-precedence layer wins, else package.json `name`
+ * (scope stripped), else the project folder name.
+ */
+function resolveAppName(layers: {
+  userConfig?: UserNexusConfig;
+  runtime?: DeepPartial<NexusConfig>;
+  env?: DeepPartial<NexusConfig>;
+  cli?: DeepPartial<NexusConfig>;
+  root: string;
+}): string {
+  const explicit =
+    layers.cli?.app?.name ??
+    layers.env?.app?.name ??
+    layers.runtime?.app?.name ??
+    layers.userConfig?.app?.name;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(layers.root, 'package.json'), 'utf8')) as { name?: string };
+    if (pkg.name) return pkg.name.replace(/^@[^/]+\//, '').trim();
+  } catch {
+    // no package.json
+  }
+  return layers.root.split(/[\\/]/).filter(Boolean).pop() ?? 'nexus';
+}
+
+/**
+ * Derive the per-project identity fields from `app.name`. Values are only
+ * applied as a base layer — an explicit value in a higher config layer wins
+ * (including `NEXUS_DB_URI`, which maps to `db.mongodb.uri` via the legacy
+ * flat shape).
+ */
+function deriveAppIdentity(appName: string): DeepPartial<NexusConfig> {
+  return {
+    app: { name: appName },
+    auth: {
+      jwt: { issuer: appName, audience: `${appName}-client` },
+      cookieName: `${appName}_sid`,
+      refreshCookieName: `${appName}_rid`,
+    },
+    redis: { keyPrefix: `${appName}:` },
+    db: { mongodb: { uri: `mongodb://localhost:27017/${appName}` } },
+    email: { from: `no-reply@${appName}.local` },
+  };
+}
+
 async function importUserConfig(absPath: string): Promise<UserNexusConfig> {
   const url = pathToFileURL(absPath).href;
   const mod = (await import(url)) as Record<string, unknown>;
@@ -155,7 +223,13 @@ export async function loadConfigAuto(
   });
 }
 
-/** Read-only accessor for tests / bootstrap that don't need file loading. */
+/**
+ * Read-only accessor for tests / bootstrap that don't need file loading.
+ * When any source declares `app.name`, the derived identity fields are applied
+ * as a base layer (an explicit value in a later source still wins).
+ */
 export function mergeConfig(...sources: DeepPartial<NexusConfig>[]): NexusConfig {
-  return Object.freeze(nexusConfigSchema.parse(deepMerge(defaults, ...sources))) as NexusConfig;
+  const explicitName = [...sources].reverse().find((s) => s?.app?.name)?.app?.name;
+  const base = explicitName ? deepMerge(defaults, deriveAppIdentity(explicitName)) : defaults;
+  return Object.freeze(nexusConfigSchema.parse(deepMerge(base, ...sources))) as NexusConfig;
 }

package/src/config/current.ts

@@ -0,0 +1,28 @@
+/**
+ * Process-wide accessor for the loaded config.
+ *
+ * `createNexusApp()` registers the merged config here at boot so code paths
+ * that are not handed a `ctx` (subgraphs, services, listeners, jobs) can read
+ * the same identity/namespace values instead of hardcoding them.
+ *
+ * This is a convenience fallback, not a replacement for DI — prefer the
+ * `ctx.config` / resolver-context value when a request context is available.
+ */
+import type { NexusConfig } from './types.js';
+
+let current: NexusConfig | null = null;
+
+/** Register the config for this process (called by createNexusApp at boot). */
+export function setNexusConfig(config: NexusConfig): void {
+  current = config;
+}
+
+/** The config registered for this process, or null before boot. */
+export function getNexusConfig(): NexusConfig | null {
+  return current;
+}
+
+/** Reset the process config (tests / hot reload). */
+export function resetNexusConfig(): void {
+  current = null;
+}

package/src/config/dbAccess.ts

@@ -24,3 +24,24 @@ export function fusionEnabled(config: NexusConfig): boolean {
 export function fusionDir(config: NexusConfig): string {
   return config.db.fusion.dir;
 }
+
+/** True when the backend delegates to a standalone Fusion server over HTTP
+ *  (no in-process engine). Triggered by `db.fusion.remote` or a set `url`. */
+export function fusionRemote(config: NexusConfig): boolean {
+  return config.db.fusion.remote === true || !!config.db.fusion.url;
+}
+
+/** Standalone Fusion server base URL (empty when embedded). */
+export function fusionUrl(config: NexusConfig): string {
+  return config.db.fusion.url ?? '';
+}
+
+/** Which backend serves cache duties — 'fusion' (default) or 'redis'. */
+export function cacheActive(config: NexusConfig): 'fusion' | 'redis' {
+  return config.cache?.active ?? 'fusion';
+}
+
+/** True when the app uses an external Redis server for cache. */
+export function redisCacheEnabled(config: NexusConfig): boolean {
+  return cacheActive(config) === 'redis';
+}

package/src/config/defaults.ts

@@ -6,6 +6,11 @@ import type { NexusConfig } from './types.js';
  */
 export const defaults: NexusConfig = {
   env: 'development',
+  app: {
+    // Overridden by ConfigLoader with the project slug (package.json name or
+    // folder name) when not set explicitly in nexus.config.ts.
+    name: 'nexus',
+  },
   server: {
     port: 4000,
     host: 'localhost',
@@ -21,7 +26,7 @@ export const defaults: NexusConfig = {
     allowedTypes: [],
   },
   db: {
-    active: 'mongodb',
+    active: 'fusion',
     mongodb: {
       enabled: true,
       uri: 'mongodb://localhost:27017/nexus',
@@ -29,7 +34,9 @@ export const defaults: NexusConfig = {
       autoIndex: true,
     },
     fusion: {
-      enabled: false,
+      enabled: true,
+      remote: false,
+      url: '',
       dir: 'storage/fusion',
       persist: true,
       cacheCapacity: 10_000,
@@ -87,11 +94,10 @@ export const defaults: NexusConfig = {
   },
   ads: {
     enabled: false,
-    developerToken: '',
+    publisherId: '',
     clientId: '',
     clientSecret: '',
     refreshToken: '',
-    customerId: '',
   },
   webrtc: {
     rtcMinPort: 40000,
@@ -131,7 +137,7 @@ export const defaults: NexusConfig = {
     level: 'info',
     format: 'pretty',
     console: true,
-    dir: 'logs',
+    dir: 'storage/logs',
     maxFileSize: 10 * 1024 * 1024, // 10 MiB
     maxFiles: 7,
   },
@@ -149,14 +155,8 @@ export const defaults: NexusConfig = {
     host: 'localhost',
     enabled: true,
   },
-  fusion: {
-    dir: 'storage/fusion',
-    persist: true,
-    cacheCapacity: 10_000,
-    cacheTtlMs: 5_000,
-    walCompactThreshold: 1_000,
-  },
   cache: {
+    active: 'fusion',
     dir: 'storage/fusion/cache',
     persist: true,
     cacheCapacity: 10_000,

package/src/config/env.ts

@@ -50,6 +50,26 @@ function coerce(value: string): string | number | boolean {
   return v;
 }
 
+/**
+ * Runtime-only `NEXUS_*` variables that are NOT config keys.
+ *
+ * These are process controls injected by the CLI / supervisor (`nexus dev` sets
+ * NEXUS_PORT and NEXUS_PORT_STEP on every child) or read directly by the
+ * framework at boot. Mapping them into the config tree corrupts it — e.g.
+ * NEXUS_PORT creates `{ port: 4000 }` and NEXUS_PORT_STEP then tries to write
+ * `port.step` onto that number, throwing `Cannot create property 'step' on
+ * number` and killing backend boot whenever ports step up.
+ */
+const RUNTIME_ENV_VARS = new Set([
+  'NEXUS_PORT',          // per-service resolved port (read by createNexusApp)
+  'NEXUS_PORT_STEP',     // coordinated step-up delta (read by the CLI)
+  'NEXUS_HOST',          // bind host injected by the supervisor
+  'NEXUS_PROJECT_ROOT',  // license/config resolution root injected by the CLI
+  'NEXUS_TUI_NO_MOUSE',  // dev panel control
+  'NEXUS_TUI_DEBUG',     // dev panel control
+  'NEXUS_AI_FIX',        // `nexus dev --ai-fix` toggle
+]);
+
 /**
  * Two `_`-separated env segments that form ONE camelCase config field.
  * Generic splitting would turn `KEY_ID` into `key.id` (a nested object) —
@@ -69,6 +89,8 @@ const PAIR_FIELDS: Record<string, string> = {
   'webhook_secret': 'webhookSecret',
   'customer_id': 'customerId',
   'developer_token': 'developerToken',
+  'publisher_id': 'publisherId',
+  'account_id': 'accountId',
   'refresh_token': 'refreshToken',
   'access_ttl': 'accessTtl',
   'refresh_ttl': 'refreshTtl',
@@ -91,6 +113,7 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
   const out: Record<string, unknown> = {};
   for (const [rawKey, rawValue] of Object.entries(env)) {
     if (!rawKey.startsWith('NEXUS_') || rawValue === undefined) continue;
+    if (RUNTIME_ENV_VARS.has(rawKey)) continue;
     const path = rawKey.slice('NEXUS_'.length).toLowerCase().split('_');
     const last = path.length - 1;
     if (last >= 1) {
@@ -100,15 +123,37 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
       }
     }
     let node: Record<string, unknown> = out;
+    let conflict = false;
     for (let i = 0; i < path.length; i++) {
       const segment = path[i]!;
       if (i === path.length - 1) {
         node[segment] = coerce(rawValue);
       } else {
-        node[segment] = (node[segment] as Record<string, unknown>) ?? {};
-        node = node[segment] as Record<string, unknown>;
+        const existing = node[segment];
+        // A scalar here means two env vars disagree about the shape (e.g.
+        // NEXUS_SERVER_PORT=4000 plus NEXUS_SERVER_PORT_X). Overwriting would
+        // either crash (writing a property onto a primitive) or silently drop
+        // config, so skip the offending var and keep the first value.
+        if (existing !== undefined && (typeof existing !== 'object' || existing === null)) {
+          conflict = true;
+          break;
+        }
+        const child = existing ?? {};
+        node[segment] = child;
+        node = child as Record<string, unknown>;
       }
     }
+    if (conflict && !isKnownRuntimeVar(rawKey)) {
+      // Real config vars would silently vanish — make that visible.
+      console.warn(
+        `[config] ignoring ${rawKey}: its path collides with a scalar already set by another NEXUS_* var`,
+      );
+    }
   }
   return out as DeepPartial<NexusConfig>;
+}
+
+/** True for vars the framework consumes at runtime rather than as config. */
+function isKnownRuntimeVar(key: string): boolean {
+  return RUNTIME_ENV_VARS.has(key);
 }

package/src/config/index.ts

@@ -4,4 +4,5 @@ export * from './merge.js';
 export * from './env.js';
 export * from './schema.js';
 export * from './dbAccess.js';
-export * from './ConfigLoader.js';
+export * from './ConfigLoader.js';
+export * from './current.js';

package/src/config/schema.ts

@@ -11,6 +11,9 @@ const providerConfig = z
 
 export const nexusConfigSchema = z.object({
   env: z.enum(['development', 'production', 'test']).default('development'),
+  app: z.object({
+    name: z.string().min(1).default('nexus'),
+  }).default({ name: 'nexus' }),
   server: z.object({
     port: z.number().int().min(1).max(65535),
     host: z.string().min(1),
@@ -29,7 +32,7 @@ export const nexusConfigSchema = z.object({
   }),
   db: z
     .object({
-      active: z.enum(['mongodb', 'fusion']).default('mongodb'),
+      active: z.enum(['mongodb', 'fusion']).default('fusion'),
       mongodb: z
         .object({
           enabled: z.boolean().default(true),
@@ -46,7 +49,9 @@ export const nexusConfigSchema = z.object({
         }),
       fusion: z
         .object({
-          enabled: z.boolean().default(false),
+          enabled: z.boolean().default(true),
+          remote: z.boolean().default(false),
+          url: z.string().default(''),
           dir: z.string().min(1),
           persist: z.boolean().default(true),
           cacheCapacity: z.number().int().positive(),
@@ -54,7 +59,9 @@ export const nexusConfigSchema = z.object({
           walCompactThreshold: z.number().int().positive(),
         })
         .default({
-          enabled: false,
+          enabled: true,
+          remote: false,
+          url: '',
           dir: 'storage/fusion',
           persist: true,
           cacheCapacity: 10_000,
@@ -102,18 +109,21 @@ export const nexusConfigSchema = z.object({
     }),
     cookieName: z.string(),
     refreshCookieName: z.string(),
+    // NOTE: clientId/clientSecret use z.coerce.string() — env coercion turns
+    // all-digit values (e.g. numeric Meta App IDs) into numbers, and OAuth
+    // credential fields must accept them rather than crash the boot.
     google: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
       .optional(),
     facebook: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
@@ -151,11 +161,11 @@ export const nexusConfigSchema = z.object({
   }),
   ads: z.object({
     enabled: z.boolean(),
-    developerToken: z.string(),
+    publisherId: z.string(),
     clientId: z.string(),
     clientSecret: z.string(),
     refreshToken: z.string(),
-    customerId: z.string(),
+    accountId: z.string().optional(),
   }),
   webrtc: z.object({
     rtcMinPort: z.number().int().min(1).max(65535),
@@ -201,14 +211,8 @@ export const nexusConfigSchema = z.object({
     host: z.string().min(1),
     enabled: z.boolean(),
   }),
-  fusion: z.object({
-    dir: z.string().min(1).default('storage/fusion'),
-    persist: z.boolean().default(true),
-    cacheCapacity: z.number().int().positive().default(10_000),
-    cacheTtlMs: z.number().int().positive().default(5_000),
-    walCompactThreshold: z.number().int().positive().default(1_000),
-  }),
   cache: z.object({
+    active: z.enum(['fusion', 'redis']).default('fusion'),
     dir: z.string().min(1).default('storage/fusion/cache'),
     persist: z.boolean().default(true),
     cacheCapacity: z.number().int().positive().default(10_000),

package/src/config/types.ts

@@ -8,6 +8,16 @@
 
 export type Env = 'development' | 'production' | 'test';
 
+/**
+ * Project identity. `app.name` is the single source of truth for the project
+ * slug; cookie names, JWT issuer/audience, redis key prefix and mail `from`
+ * are derived from it when not set explicitly.
+ */
+export interface AppConfig {
+  /** Project slug, e.g. 'nexus-bhooai-com'. Derives auth identity + namespaces. */
+  name: string;
+}
+
 export interface ServerConfig {
   port: number;
   host: string;
@@ -23,7 +33,8 @@ export interface ServerConfig {
 }
 
 export interface UploadsConfig {
-  /** Directory for persisted files, relative to the project root. */
+  /** Directory for persisted files, relative to the storage root
+   *  (`createNexusApp`'s `storageRoot`, default = project root). */
   dir: string;
   /** Public URL path for upload and download requests. */
   path: string;
@@ -50,8 +61,19 @@ export interface MongoDbConfig {
 }
 
 export interface FusionDbConfig {
-  /** Open the Fusion engine at boot when true. Default false. */
+  /** Open the Fusion engine at boot when true. Default true. */
   enabled: boolean;
+  /**
+   * Delegate to a **standalone Fusion server** instead of opening the engine
+   * in-process. When true (or when `url` is non-empty) the backend no longer
+   * owns `storage/fusion/fusion.wal`; every read/write goes over HTTP to the
+   * `fusion` service started by `nexus dev`. This lets several apps share one
+   * Fusion database and keeps the backend process free of the Rust engine.
+   */
+  remote: boolean;
+  /** Standalone Fusion server base URL, e.g. `http://127.0.0.1:5000`.
+   *  Empty (and `remote: false`) keeps the embedded in-process engine. */
+  url: string;
   /** Durable storage dir, relative to the project root. Omit/empty for in-memory. */
   dir: string;
   /** Persist the WAL to `dir` (persist=false runs purely in-memory). */
@@ -65,7 +87,7 @@ export interface FusionDbConfig {
 }
 
 export interface DbConfig {
-  /** Which database backs the user store + ODM models. Default 'mongodb'. */
+  /** Which database backs the user store + ODM models. Default 'fusion'. */
   active: ActiveDatabase;
   mongodb: MongoDbConfig;
   fusion: FusionDbConfig;
@@ -165,11 +187,11 @@ export interface CertsConfig {
 
 export interface AdsConfig {
   enabled: boolean;
-  developerToken: string;
+  publisherId: string;
   clientId: string;
   clientSecret: string;
   refreshToken: string;
-  customerId: string;
+  accountId?: string;
 }
 
 export interface WebRtcConfig {
@@ -303,22 +325,14 @@ export interface AppPortConfig {
   enabled?: boolean;
 }
 
-export interface FusionConfig {
-  /** Durable storage dir, resolved against the backend's projectRoot. Empty or
-   *  persist=false runs the engine purely in-memory. Default 'storage/fusion'. */
-  dir: string;
-  /** When false, ignore `dir` and run purely in-memory. Default true. */
-  persist: boolean;
-  /** L1 cache capacity (entries). Default 10_000. */
-  cacheCapacity: number;
-  /** L1 cache TTL in ms. Default 5_000. */
-  cacheTtlMs: number;
-  /** WAL compaction threshold (records). Default 1_000. */
-  walCompactThreshold: number;
-}
-
 /** Redis-like FusionCache settings (`@bhooai/nexus-fusion/cache`). */
 export interface CacheConfig {
+  /** Which backend serves cache duties — 'fusion' (embedded, zero-dep,
+   *  default) or 'redis' (external server at `redis.url`). Override with
+   *  NEXUS_CACHE_ACTIVE. Single-instance apps are fully served by fusion
+   *  (strings/hashes/lists/sets + TTL); pick 'redis' for multi-instance
+   *  pub/sub fan-out. */
+  active: 'fusion' | 'redis';
   /** Durable storage dir, resolved against the backend's projectRoot. Cache
    *  lives in its own subdir (default 'storage/fusion/cache') so it never
    *  shares a WAL with the main fusion engine. */
@@ -339,6 +353,7 @@ export interface CacheConfig {
 
 export interface NexusConfig {
   env: Env;
+  app: AppConfig;
   server: ServerConfig;
   uploads: UploadsConfig;
   db: DbConfig;
@@ -356,7 +371,6 @@ export interface NexusConfig {
   plugins: PluginsConfig;
   frontend: FrontendConfig;
   admin: AdminConfig;
-  fusion: FusionConfig;
   cache: CacheConfig;
   /** Multi-app port layout. Empty = every service uses its section default. */
   apps: AppPortConfig[];

package/src/http/Server.ts

@@ -5,6 +5,7 @@ import { randomUUID } from 'node:crypto';
 import type { Middleware, RequestContext } from './context.js';
 import { createContext } from './context.js';
 import type { Router } from './Router.js';
+import type { NexusConfig } from '../config/types.js';
 import { NexusError, toNexusError } from '../errors.js';
 
 /** Generate a request id (overridable for tests/injection). */
@@ -33,6 +34,8 @@ export interface ServerOptions {
   renderError?: (err: unknown, ctx: RequestContext) => Promise<void> | void;
   /** Custom 404 renderer for unmatched routes. Falls back to JSON. */
   renderNotFound?: (ctx: RequestContext) => Promise<void> | void;
+  /** Loaded project config, exposed to handlers as `ctx.config`. */
+  config?: NexusConfig;
 }
 
 /**
@@ -87,6 +90,7 @@ export class NexusServer {
     const requestId = (req.headers['x-request-id'] as string) ?? newRequestId();
     res.setHeader('x-request-id', requestId);
     const ctx = createContext(req, res, requestId);
+    ctx.config = this.opts.config ?? null;
 
     try {
       await this.runPipeline(ctx);

package/src/http/context.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Socket } from 'node:net';
+import type { NexusConfig } from '../config/types.js';
 
 /** Route path parameters extracted from the URL. */
 export type Params = Record<string, string>;
@@ -26,6 +27,11 @@ export interface RequestContext {
   body: unknown;
   /** Per-request state. */
   state: State;
+  /**
+   * The loaded project config. Injected by NexusServer at request time; may be
+   * null when a context is built standalone (e.g. in tests).
+   */
+  config?: NexusConfig | null;
   /** Request id (also in headers as x-request-id). */
   requestId: string;
   /** The matched route pattern, e.g. "/users/:id". */

package/tests/config.test.ts

@@ -25,6 +25,57 @@ describe('configFromEnv', () => {
     expect((cfg as any).ai?.serverUrl).toBe('http://ai:8000');
     expect((cfg as any).ai?.server?.url).toBeUndefined();
   });
+
+  it('accepts a numeric Meta App ID for auth.facebook.clientId', () => {
+    // Env coercion turns all-digit values into numbers; the schema must
+    // coerce them back so boot does not crash (ZodError on auth.facebook.clientId).
+    const partial = configFromEnv({ NEXUS_AUTH_FACEBOOK_CLIENT_ID: '123456789012345' });
+    expect((partial as any).auth?.facebook?.clientId).toBe(123456789012345);
+    const cfg = mergeConfig({
+      auth: {
+        facebook: {
+          clientId: (partial as any).auth.facebook.clientId,
+          clientSecret: 's3cret',
+          callbackPath: '/auth/facebook/callback',
+          scope: 'email',
+        },
+      },
+    });
+    expect(cfg.auth.facebook?.clientId).toBe('123456789012345');
+  });
+});
+
+describe('app identity derivation', () => {
+  it('derives auth/redis/mongo/email identity from app.name', () => {
+    const cfg = mergeConfig({ app: { name: 'my-app' } });
+    expect(cfg.app.name).toBe('my-app');
+    expect(cfg.auth.jwt.issuer).toBe('my-app');
+    expect(cfg.auth.jwt.audience).toBe('my-app-client');
+    expect(cfg.auth.cookieName).toBe('my-app_sid');
+    expect(cfg.auth.refreshCookieName).toBe('my-app_rid');
+    expect(cfg.redis.keyPrefix).toBe('my-app:');
+    expect(cfg.db.mongodb.uri).toBe('mongodb://localhost:27017/my-app');
+    expect(cfg.email.from).toBe('no-reply@my-app.local');
+  });
+
+  it('lets an explicit mongo uri override the derived one', () => {
+    const cfg = mergeConfig({
+      app: { name: 'my-app' },
+      db: { mongodb: { uri: 'mongodb://remote:27017/custom' } },
+    });
+    expect(cfg.db.mongodb.uri).toBe('mongodb://remote:27017/custom');
+  });
+
+  it('lets an explicit value override the derived default', () => {
+    const cfg = mergeConfig({ app: { name: 'my-app' }, auth: { cookieName: 'custom_sid' } });
+    expect(cfg.auth.cookieName).toBe('custom_sid');
+    expect(cfg.auth.jwt.issuer).toBe('my-app');
+  });
+
+  it('defaults app.name to nexus when unset', () => {
+    const cfg = mergeConfig({});
+    expect(cfg.app.name).toBe('nexus');
+  });
 });
 
 describe('mergeConfig', () => {