TREK/server/src/app-config/README.md

app-config — TREK's environment configuration layer

One validated source of truth for every environment variable the server reads. Framework-free (no Nest imports), so it is consumable from anywhere: Nest DI classes, the legacy free-function services, mcp, websocket, scheduler, db and the pre-init Express middleware.

env.schema.ts    Zod catalog of the whole env surface; fail-fast at boot
derive.ts        pure (raw env) → typed namespace functions, exact per-site coercions
env.ts           readEnv() live accessor + validateEnvAtBoot()
app-url.ts       getAppUrl()/getMcpSafeUrl() instance base-URL resolution
data-paths.ts    resolveDataPaths(): data/, uploads/, backups, tmp, logs, key files, DB file
boot-validate.ts side-effect import used by index.ts (validates before other modules load)
parsers.ts       shared coercion helpers (boolTrueLoose, numberOr, csvList, …)

The Nest binding lives in src/nest/app-config/ (AppConfigModule, registerAs tokens, RuntimeEnvService) and consumes the SAME derive functions.

Invariants — read before touching anything here

1. readEnv() is live. It re-derives from the current process.env on every call, with no caching or memoization, ever. ~60 test files mutate process.env at runtime and depend on the next read observing the change.
2. Validation runs once, at boot, from the production entrypoint only. Never wire the schema into buildApp(), ConfigModule.forRoot({ validate }) or a request path. Unset/blank variables always pass (defaults apply); only present-but-malformed values abort startup. The one addition on top of the schema is managedPreconditions() in env.ts: cross-field rules that only apply with TREK_MANAGED, for combinations that are individually valid and together wrong. It is empty without the switch, so a self-hoster never meets it. Put a rule there only if booting anyway would be a security or data problem — not to enforce a preference. The report prints each malformed value, because that is what makes a typo findable, except for the credentials in SECRET_ENV_KEYS (env.ts), which print as ***. A new password, token, key or secret variable goes into that set; validate.test.ts fails on a credential-sounding name missing from it.
3. Parity is law — with one deliberate exception. Every derived field pins the exact coercion of the call site(s) it replaced (Number(x) || d treating "0" as unset, per-site defaults for the same variable, …). Do not "fix" a quirk here; log it as a follow-up instead. The exception: boolean switches are unified through parseBool — every boolean-like variable accepts true/1/on/yes and false/0/off/no (any casing) and derives to a real boolean. This intentionally replaces the legacy per-site literals ('true' here, '1' there, 'on' elsewhere); tests that pinned those narrow literals get updated when their call site migrates.
4. Env vs DB-setting layering stays at the call site. For process.env.X || getSetting('x') patterns, this layer supplies only the env half; the runtime-mutable admin-setting fallback remains inline where it was.
5. Never convert a frozen read to a live read or vice versa. Modules that captured env in module-top consts (mcp, backupService, ssrfGuard, plugin rate limits, …) keep freeze-at-import timing, merely sourcing the value from readEnv() at module top. Request-time reads stay request-time.

data-paths.ts: the one data layout

resolveDataPaths() is the only place the server anchors data/ and uploads/ (on SERVER_ROOT, the package directory, never on process.cwd()) and names what lives in them: backups, the scratch dir, the logs, the JWT secret and encryption key files, and the database file (TREK_DB_FILE when set, else data/travel.db). Never derive one of these paths from __dirname in a new file: a moved file would quietly move the data.

Two ways in, by where the code runs:

• Nest providers inject DataPathsService (src/nest/app-config/), which resolves the same layout once per built app: AdminService (the JWT secret file), StorageRegistryService (the built-in uploads and backups roots and the scratch dir) and, through StorageRegistryService.tempDir(), StorageJobsService. A new provider that needs a data path takes it the same way.
• Plain modules call resolveDataPaths() because they run without a container or are shared with code that does: config.ts key resolution, db/db-path.ts, index.ts, the file logger, demo/demo-reset.ts, the backup restore and archive functions (nest/backup/backup.impl.ts, auto-backup.settings.ts, file I/O with no container state), the plugin trees (nest/plugins/paths.ts, also read by the out-of-process supervisor), and nest/storage/storage-paths.ts, which keeps the seed-config test seam that StorageAdminService and the registry share. files.constants.ts still exports filesDir for the tests that pin the layout; no production code reads it.

app-url.ts — instance base-URL resolution (moved 2026-07-28)

getAppUrl() (APP_URL → first ALLOWED_ORIGINS entry → http://localhost:PORT, each candidate URL-validated, ALL trailing slashes stripped) and getMcpSafeUrl() (same, sanitized to HTTPS/localhost/127.0.0.1 for the MCP SDK's issuer check) moved here verbatim from services/notifications.ts (audit findings auth-2/notifications-1/admin-3/mcp-1). They follow invariant 1: readEnv() per call, live, never cached. The invalid-URL silent fallthrough and the strip-ALL-slashes quirk (see parsers.ts stripTrailingSlashes) are parity-pinned — do not "fix" them here.

Ownership: one door per variable

Every variable has exactly one owner, and the owner decides how it is read:

• A registerAs token (src/nest/app-config/tokens.ts, derived by boot-derive.ts): boot-stable values that only Nest classes need. The token is snapshotted per built app and injected (@Inject(storageConfig.KEY), or app.get(httpConfig.KEY) for the pre-init Express layer). Today: httpConfig (TRUST_PROXY, HSTS_INCLUDE_SUBDOMAINS, HTTP_KEEP_ALIVE_TIMEOUT_MS), storageConfig (TREK_PLACE_PHOTO_DIR), transitConfig (TRANSIT_API_URL, for TransitService) and kitineraryConfig (KITINERARY_EXTRACTOR_PATH and PATH, for KitineraryExtractorService's binary probe). A module whose provider injects one imports AppConfigModule, so it also builds on its own in a test.
• readEnv() / RuntimeEnvService (derive.ts): everything else, both the runtime-toggled values and the boot-stable ones that code outside a Nest provider reads, which freezes them in module-top consts. Each of those has a reader the container cannot inject into:
  • PORT, HOST: index.ts, before the app exists.
  • SESSION_DURATION(_REMEMBER), DEFAULT_LANGUAGE, ENCRYPTION_KEY: src/config.ts, a plain module evaluated at process start.
  • MCP_*: src/mcp/, the process-wide session state.
  • TREK_PLUGIN_RPC_/LOG_/MAX_RSS_MB: the plugin host and supervisor, which are deliberately not Nest (the sandbox boundary).
  • TREK_PLUGIN_REGISTRY_URL: PluginRegistryService is a provider, but several plugin suites build it by hand with a trailing @Optional() UnitOfWork, so a required token parameter cannot go in without reordering that signature.
  • TREK_WIKI_DIR: nest/help/wiki.ts, a plain module the help MCP tools call.
  • BACKUP_*: nest/backup/backup-archive.ts, which the first-start restore (boot-restore.ts, called from index.ts) runs before the database opens.
  • LOG_LEVEL: the logger, imported everywhere.
  • ALLOW_INTERNAL_NETWORK, ALLOW_LINK_LOCAL_IPS: the SSRF guard in utils/.
  • TREK_DB_FILE, TREK_DB_JOURNAL_MODE, TREK_DB_SYNCHRONOUS: the database, opened before the container.

deriveAll() never reads a variable a token owns, and a token is dropped once nothing injects it. tests/unit/app-config/config-ownership.test.ts records the keys each side reads through a Proxy and fails on an overlap, on a token without a consumer and on a variable the schema does not validate. Moving a variable to a token means moving its field from derive.ts to boot-derive.ts and converting every reader in the same change.

server/.env.example names every variable the schema validates except the few in env-reference.test.ts's NOT_OPERATOR_SETTINGS; that test fails on drift in either direction. The managed-hosting switches (TREK_MANAGED and the keys only a managed install sets: MAPBOX_ACCESS_TOKEN, CARTO_API_KEY, PLACES_API_BASE) are on that list on purpose and stay out of every public reference.

Classification: boot-stable vs runtime-toggled

Boot-stable (frozen at app/module creation; a registerAs token where the variable is token-owned, module-top readEnv() consts elsewhere): PORT, HOST, TRUST_PROXY, HSTS_INCLUDE_SUBDOMAINS, HTTP_KEEP_ALIVE_TIMEOUT_MS, SESSION_DURATION(REMEMBER), MCP_SESSION_TTL, MCP_MAX_SESSION_PER_USER, MCP_SSE_KEEPALIVE, TREK_PLUGIN_RPC/LOG_/MAX_RSS_MB, TREK_PLUGIN_REGISTRY_URL, TREK_WIKI_DIR*, TREK_PLACE_PHOTO_DIR, BACKUP_, TRANSIT_API_URL, KITINERARY_EXTRACTOR_PATH, LOG_LEVEL, ALLOW_INTERNAL_NETWORK*, ALLOW_LINK_LOCAL_IPS*, DEFAULT_LANGUAGE, TREK_DB_FILE, TREK_DB_JOURNAL_MODE, TREK_DB_SYNCHRONOUS, ENCRYPTION_KEY**. (* frozen today because the consuming module captures it at import; tests that override these set them at file top, before the SUT import.) (** ENCRYPTION_KEY is boot-stable for the cipher key material itself — src/config.ts resolves and freezes it at process start, per the exemption below.)

Runtime-toggled (read live on every access via readEnv() / RuntimeEnvService; tests mutate these mid-lifetime): TREK_MANAGED, PLACES_API_BASE, PLACES_API_KEY, AMAP_API_BASE, AMAP_API_KEY, AMAP_API_SECRET, MAPBOX_ACCESS_TOKEN, CARTO_API_KEY, DEMO_MODE, NODE_ENV, APP_VERSION, APP_URL, TREK_API_DOCS_ENABLED, TREK_PLUGINS_ENABLED / _DEV_LINK / IGNORE_TREK_RANGE / DIR / DATA_DIR / TREK_PLUGIN_PERMISSIONS, OIDC*, SMTP*, FORCE_HTTPS, COOKIE_SECURE, ALLOWED_ORIGINS, UNSPLASH_ACCESS_KEY, WEBAUTHN, TZ, ADMIN_EMAIL, TREK_DB_PRE_MIGRATE_SNAPSHOT(KEEP) (read when a migration run starts; the legacy-upgrade suites set it per file), ADMIN_PASSWORD, IDEMPOTENCY_TTL_SECONDS, MCP_RATE_LIMIT (request-path check), LLM_TIMEOUT_MS, NOMINATIM_URL, VAPID (resolved per use by the Web Push key service, which the notification suites build without the container).

Exemptions — raw process.env stays

• src/nest/plugins/runtime/plugin-host-entry.ts — runs in a scrubbed child process; must not import this layer.
• src/nest/plugins/supervisor/plugin-supervisor.ts child-env whitelist block — the env there is an IPC channel to the sandbox, not app configuration.
• Dynamic-key reads (process.env[name]) in plugins/host/daily-budget.ts and plugins/host/plugin-audit.ts.
• src/config.ts ENCRYPTION_KEY/JWT_SECRET resolution — key material with file persistence and runtime rotation, not env config.
• Standalone scripts (reset-admin.js, scripts/*) and tests/**. Note that reset-admin.js and scripts/migrate-encryption.ts open the database file read-write and therefore re-implement TREK_DB_JOURNAL_MODE / TREK_DB_SYNCHRONOUS inline (the journal mode lives in the file header, so they must agree with the server). Neither can import this layer — the image ships dist/, not src/ — so the defaults in parsers.resolveDurability() and in those two files move together.

The exemption list is enforced by the no-restricted-syntax ban on process.env in eslint.config.mjs — keep the two lists in sync.

Follow-up candidates (quirks pinned during the migration, deliberately NOT fixed)

• numberOr (Number(x) || d) treats "0" and negative-invalid values oddly: PORT=0 silently becomes 3001, TREK_PLUGIN_RPC_BURST=-5 stays -5.
• APP_URL trailing-slash stripping differs per site (feeds strips one slash, notifications strips all).
• DEMO_ADMIN_EMAIL defaults differ (demo-seed: admin@trek.app, demo-reset: admin@nomad.app).
• NODE_ENV comparisons are case-sensitive at some sites (HSTS activation, platform statics, spa-fallback, authService dev_mode, oidcService frontendUrl) and case-insensitive at others.