Files
TREK/server/tests/unit/app-config/validate.test.ts
T
Isaias Tavares 25f5e34558 feat(db): choose the database engine from TREK_DB_URL
A port for the engine TREK runs on, without changing what it runs on.
src/db/engine/ names the engine (SqliteEngine, PostgresEngine) and builds
the MikroORM config from it; src/mikro-orm.config.ts exports that config for
the CLI and the Nest container alike. Without TREK_DB_URL the config is the
one it was: the shared SQLite driver on TREK_DB_FILE or data/travel.db.

- TREK_DB_URL takes a postgres:// or postgresql:// URL and is masked in the
  boot report; TREK_DB_POOL_MAX sizes the pool (1 to 100, default 10).
  TREK_DB_URL beside TREK_DB_FILE, TREK_DB_JOURNAL_MODE or
  TREK_DB_SYNCHRONOUS refuses the boot as an ambiguous configuration.
- MikroORM builds the pg pool from the URL's host, port, user, password and
  database and drops the rest of the query, so the engine reads sslmode and
  sslrootcert itself. require, verify-ca and verify-full all verify the
  server's certificate, as the pg driver reads them; a mode that would not
  verify, or a misspelt one, refuses.
- Postgres cannot run TREK yet, so a boot with TREK_DB_URL is refused with
  that reason, in the boot check and again where the config is built, before
  anything connects.
- @mikro-orm/postgresql moves to dependencies; pg is plain JavaScript.
- lint:engine-dispatch (CI) holds the engine checks outside src/db/dialect/
  and src/db/engine/ (isSqlite(, isPostgres(, an instanceof on a platform, a
  comparison on the engine's name) to a baseline that starts and stays empty.
2026-11-04 22:45:02 -03:00

384 lines
17 KiB
TypeScript

import { validateEnvAtBoot, readEnv, SECRET_ENV_KEYS } from '../../../src/app-config/env';
import { envSchema } from '../../../src/app-config/env.schema';
import { describe, it, expect, vi, afterEach } from 'vitest';
import type { z } from 'zod';
const schemaShape: Record<string, z.ZodType> = envSchema.shape;
/**
* A value no check of the schema accepts (not a number, URL, boolean, duration,
* language or base64url key), and one that names its variable, so a leak is
* traceable to the key it came from.
*/
const probe = (key: string): string => `probe+${key}/not valid=`;
/** Everything one boot check printed and threw. */
function bootReport(raw: Record<string, string>): { printed: string; thrown: string } {
const error = vi.spyOn(console, 'error').mockImplementation(() => {});
let thrown = '';
try {
validateEnvAtBoot(raw);
} catch (err) {
thrown = err instanceof Error ? err.message : String(err);
}
const printed = error.mock.calls.map((c) => c.join(' ')).join('\n');
error.mockRestore();
return { printed, thrown };
}
describe('validateEnvAtBoot', () => {
afterEach(() => {
vi.restoreAllMocks();
});
it('passes with a completely empty environment (all defaults)', () => {
expect(() => validateEnvAtBoot({})).not.toThrow();
});
it('passes with a representative valid environment', () => {
expect(() =>
validateEnvAtBoot({
PORT: '3001',
NODE_ENV: 'production',
DEMO_MODE: 'false',
SESSION_DURATION: '12h',
SESSION_DURATION_REMEMBER: '90d',
DEFAULT_LANGUAGE: 'en',
APP_URL: 'https://trek.example.com',
ALLOWED_ORIGINS: 'https://trek.example.com',
LOG_LEVEL: 'debug',
TRUST_PROXY: '2',
OIDC_ISSUER: 'https://auth.example.com/realms/trek',
SMTP_PORT: '587',
MCP_RATE_LIMIT: '100',
BACKUP_UPLOAD_LIMIT_MB: '750',
TREK_PLUGINS_ENABLED: 'off',
TREK_PLUGIN_PERMISSIONS: 'on',
}),
).not.toThrow();
});
it('refuses an LLM ceiling that would silently become a zero timeout', () => {
// Both shapes pass a plain "positive number" check and then degrade into an
// immediate abort: a fractional value floors to 0, and anything past the
// 32-bit range makes Node clamp the setTimeout delay to 1 ms. The wiki
// promises invalid values abort startup, so they have to refuse here.
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '0.5' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '900000.5' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '2147483648' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '0' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '-1' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: 'abc' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '900000' })).not.toThrow();
expect(() => validateEnvAtBoot({ LLM_TIMEOUT_MS: '' })).not.toThrow();
});
it('refuses an LLM answer cap that is no whole token count or too small to hold a booking (#2677)', () => {
expect(() => validateEnvAtBoot({ LLM_MAX_OUTPUT_TOKENS: '8192.5' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_MAX_OUTPUT_TOKENS: '100' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_MAX_OUTPUT_TOKENS: 'lots' })).toThrow();
expect(() => validateEnvAtBoot({ LLM_MAX_OUTPUT_TOKENS: '16384' })).not.toThrow();
expect(() => validateEnvAtBoot({ LLM_MAX_OUTPUT_TOKENS: '' })).not.toThrow();
});
it('refuses an ALLOW_LINK_LOCAL_IPS entry that is not a listable link-local address', () => {
// A metadata address would be dropped silently at runtime; saying so at boot
// is the difference between an OIDC login that works and a puzzling one.
expect(() => validateEnvAtBoot({ ALLOW_LINK_LOCAL_IPS: '169.254.169.254' })).toThrow();
expect(() => validateEnvAtBoot({ ALLOW_LINK_LOCAL_IPS: '169.254.1.2,192.168.1.2' })).toThrow();
expect(() => validateEnvAtBoot({ ALLOW_LINK_LOCAL_IPS: '169.254.1.2' })).not.toThrow();
expect(() => validateEnvAtBoot({ ALLOW_LINK_LOCAL_IPS: '' })).not.toThrow();
});
it('checks the VAPID_* shapes and lets a well-formed set through', () => {
// The application server pair from RFC 8291 Appendix A, in the form the Web Push tools print.
const publicKey = 'BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8';
const privateKey = 'yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw';
expect(() =>
validateEnvAtBoot({
VAPID_PUBLIC_KEY: publicKey,
VAPID_PRIVATE_KEY: privateKey,
VAPID_SUBJECT: 'mailto:ops@example.com',
}),
).not.toThrow();
expect(() => validateEnvAtBoot({ VAPID_SUBJECT: 'https://trek.example.com' })).not.toThrow();
// Whether the halves belong together is checked where they are used, not here.
expect(() => validateEnvAtBoot({ VAPID_PRIVATE_KEY: privateKey })).not.toThrow();
vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() => validateEnvAtBoot({ VAPID_PUBLIC_KEY: privateKey })).toThrow();
expect(() => validateEnvAtBoot({ VAPID_PUBLIC_KEY: `A${publicKey.slice(1)}` })).toThrow();
expect(() => validateEnvAtBoot({ VAPID_PRIVATE_KEY: publicKey })).toThrow();
expect(() => validateEnvAtBoot({ VAPID_PRIVATE_KEY: 'yfWPiYE+n46HLnH0KqZOF1fJJU3MYrct3AELtAQ/oRw' })).toThrow();
expect(() => validateEnvAtBoot({ VAPID_SUBJECT: 'ops@example.com' })).toThrow();
expect(() => validateEnvAtBoot({ VAPID_SUBJECT: 'http://trek.example.com' })).toThrow();
});
it('never prints the value of a secret variable, only its name and the problem', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {});
// 43 characters like a real key, with one character base64url does not have.
const leakedPrivateKey = 'yfWPiYE+n46HLnH0KqZOF1fJJU3MYrct3AELtAQ/oRw';
expect(() => validateEnvAtBoot({ VAPID_PRIVATE_KEY: leakedPrivateKey, PORT: 'not-a-port' })).toThrow(/2 problems/);
const report = error.mock.calls.map((c) => c.join(' ')).join('\n');
expect(report).toContain('VAPID_PRIVATE_KEY=***: must be a base64url-encoded P-256 private key');
expect(report).not.toContain(leakedPrivateKey);
expect(report).not.toContain('yfWPiYE');
// Everything else keeps its value, which is what makes a typo findable.
expect(report).toContain('PORT="not-a-port"');
});
it('never prints any secret variable, whether or not its own check refuses the value', () => {
// A broken PORT guarantees a report, so every secret gets its chance to leak into it.
const { printed, thrown } = bootReport({
...Object.fromEntries([...SECRET_ENV_KEYS].map((key) => [key, probe(key)])),
PORT: 'not-a-port',
});
expect(thrown).toMatch(/Invalid environment configuration/);
expect(printed).toContain('PORT="not-a-port"');
let refused = 0;
for (const key of SECRET_ENV_KEYS) {
expect(printed, key).not.toContain(probe(key));
expect(thrown, key).not.toContain(probe(key));
if (!schemaShape[key].safeParse(probe(key)).success) {
refused += 1;
expect(printed, key).toContain(` - ${key}=***: `);
}
}
// The masking only proves itself on a variable the schema refuses.
expect(refused).toBeGreaterThan(0);
});
it('still prints the value of every variable that is not a secret', () => {
const open = Object.keys(schemaShape).filter((key) => !SECRET_ENV_KEYS.has(key));
const { printed } = bootReport(Object.fromEntries(open.map((key) => [key, probe(key)])));
// Free-form variables accept anything, so only the checked ones show up.
const refused = open.filter((key) => !schemaShape[key].safeParse(probe(key)).success);
expect(refused).toContain('VAPID_PUBLIC_KEY');
for (const key of refused) expect(printed, key).toContain(` - ${key}=${JSON.stringify(probe(key))}: `);
expect(printed.split('\n').filter((line) => line.startsWith(' - '))).toHaveLength(refused.length);
});
it('knows every secret-looking variable of the schema as a secret, and nothing the schema does not know', () => {
// A new variable with a word in its name that suggests a credential lands
// here and has to be decided on. Whole words, so OVERPASS_URL and
// WEBAUTHN_RP_ID do not count.
const looksSecret = (key: string): boolean =>
/(^|_)(SECRET|PASS(WORD|PHRASE)?|TOKEN|KEY|APIKEY|CREDENTIALS?|PRIVATE|LICEN[CS]E|WEBHOOK|AUTH|DSN|SALT)(_|$)/.test(
key,
);
const notSecret = new Set([
'VAPID_PUBLIC_KEY', // the public half, which every subscribing browser receives
'TREK_PLUGIN_ALLOW_PRIVATE_EGRESS', // a switch about private networks, not a private value
]);
const schemaKeys = Object.keys(schemaShape);
const flagged = schemaKeys.filter((key) => looksSecret(key) && !notSecret.has(key));
expect(flagged.length).toBeGreaterThan(5);
for (const key of flagged) expect(SECRET_ENV_KEYS.has(key), key).toBe(true);
for (const key of SECRET_ENV_KEYS) expect(schemaKeys, key).toContain(key);
for (const key of notSecret) {
expect(schemaKeys, key).toContain(key);
expect(looksSecret(key), key).toBe(true);
expect(SECRET_ENV_KEYS.has(key), key).toBe(false);
}
});
it('treats blank values as unset (defaults apply, no error)', () => {
expect(() => validateEnvAtBoot({ DEMO_MODE: '', PORT: ' ', TZ: '' })).not.toThrow();
});
it('ignores unknown environment variables', () => {
expect(() => validateEnvAtBoot({ SOME_OTHER_TOOLS_VAR: '!!not-a-trek-var!!' })).not.toThrow();
});
it('does not validate NODE_ENV (non-standard values must keep booting)', () => {
expect(() => validateEnvAtBoot({ NODE_ENV: 'staging' })).not.toThrow();
});
it('throws on present-but-malformed values with an aggregated report', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() =>
validateEnvAtBoot({
PORT: 'not-a-port',
SESSION_DURATION: 'bogus',
DEMO_MODE: 'maybe',
APP_URL: 'not a url',
}),
).toThrow(/Invalid environment configuration \(4 problems\)/);
const report = error.mock.calls.map((c) => c.join(' ')).join('\n');
expect(report).toContain('PORT="not-a-port"');
expect(report).toContain('SESSION_DURATION="bogus"');
expect(report).toContain('DEMO_MODE="maybe"');
expect(report).toContain('APP_URL="not a url"');
});
it.each([
['PORT', '70000'],
['TRUST_PROXY', '1.5'],
['HTTP_KEEP_ALIVE_TIMEOUT_MS', '500'],
['HTTP_KEEP_ALIVE_TIMEOUT_MS', '300000'],
['DEFAULT_LANGUAGE', 'klingon'],
['LOG_LEVEL', 'verbose'],
['SESSION_DURATION_REMEMBER', '-1d'],
['OIDC_ISSUER', 'auth.example.com'],
['SMTP_PORT', 'smtp'],
['MCP_SSE_KEEPALIVE', '-1'],
['IDEMPOTENCY_TTL_SECONDS', '0'],
['BACKUP_UPLOAD_LIMIT_MB', '0'],
['HSTS_INCLUDE_SUBDOMAINS', 'enabled'],
['TREK_PLUGINS_ENABLED', 'maybe'],
['TREK_PLUGINS_DEV_LINK', 'always'],
['TREK_PLUGIN_PERMISSIONS', 'disabled'],
['TREK_PLUGIN_MAX_RSS_MB', '-100'],
])('rejects malformed %s=%s', (key, value) => {
vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() => validateEnvAtBoot({ [key]: value })).toThrow(/Invalid environment configuration/);
});
it.each([
['DEMO_MODE', 'TRUE'],
['TREK_API_DOCS_ENABLED', ' TRUE '],
['TREK_PLUGINS_ENABLED', ' OFF '],
['DEFAULT_LANGUAGE', 'EN'],
['DEFAULT_LANGUAGE', 'zh-TW'],
['LOG_LEVEL', 'ERROR'],
['SESSION_DURATION', ' 12H '],
])('accepts differently-cased/padded valid %s=%s', (key, value) => {
expect(() => validateEnvAtBoot({ [key]: value })).not.toThrow();
});
// Booleans accept the whole boolean-like family (true/false, 1/0, on/off,
// yes/no) and derive to real booleans via parseBool — DEMO_MODE=yes enables
// demo mode, TREK_PLUGINS_DEV_LINK=true activates dev-link (see derive.test).
it.each([
['DEMO_MODE', 'yes'],
['HSTS_INCLUDE_SUBDOMAINS', '1'],
['TREK_PLUGINS_DEV_LINK', 'true'],
['TREK_PLUGIN_PERMISSIONS', 'off'],
['TREK_PLUGIN_ALLOW_PRIVATE_EGRESS', 'on'],
['FORCE_HTTPS', 'On'],
])('accepts boolean-like %s=%s', (key, value) => {
expect(() => validateEnvAtBoot({ [key]: value })).not.toThrow();
});
});
describe('validateEnvAtBoot — centrally administered preconditions', () => {
afterEach(() => {
vi.restoreAllMocks();
});
it('MANAGED-BOOT-001: refuses TREK_MANAGED without ENCRYPTION_KEY', () => {
// The combination boots fine and is wrong: the at-rest key falls back to a
// file in the data volume, and backupService puts that file in every archive
// an instance admin can download.
vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() => validateEnvAtBoot({ TREK_MANAGED: '1' })).toThrow(/1 problem/);
});
it('MANAGED-BOOT-002: names the variable, so the fix does not need the source', () => {
const err = vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() => validateEnvAtBoot({ TREK_MANAGED: 'true' })).toThrow();
expect(err.mock.calls[0][0]).toMatch(/ENCRYPTION_KEY/);
});
it('MANAGED-BOOT-003: passes once the key is supplied', () => {
expect(() => validateEnvAtBoot({ TREK_MANAGED: '1', ENCRYPTION_KEY: 'a'.repeat(64) })).not.toThrow();
});
it('MANAGED-BOOT-004: inert without the switch — a self-hoster keeps the file-based key', () => {
// The whole point of the check is that it cannot reach anyone who did not
// ask to be centrally administered.
expect(() => validateEnvAtBoot({})).not.toThrow();
expect(() => validateEnvAtBoot({ TREK_MANAGED: 'off' })).not.toThrow();
expect(() => validateEnvAtBoot({ TREK_MANAGED: 'false' })).not.toThrow();
});
it('MANAGED-BOOT-005: reports alongside schema problems rather than instead of them', () => {
// Both kinds land in one report: fixing the env should take one pass, not a
// restart per problem.
const err = vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() => validateEnvAtBoot({ TREK_MANAGED: '1', PORT: 'not-a-port' })).toThrow(/2 problems/);
expect(err.mock.calls[0][0]).toMatch(/PORT/);
expect(err.mock.calls[0][0]).toMatch(/ENCRYPTION_KEY/);
});
});
describe('readEnv', () => {
it('reads process.env live — a runtime mutation is visible on the next call', () => {
const before = process.env.DEMO_MODE;
try {
process.env.DEMO_MODE = 'true';
expect(readEnv().demo.enabled).toBe(true);
process.env.DEMO_MODE = 'false';
expect(readEnv().demo.enabled).toBe(false);
delete process.env.DEMO_MODE;
expect(readEnv().demo.enabled).toBe(false);
} finally {
if (before === undefined) delete process.env.DEMO_MODE;
else process.env.DEMO_MODE = before;
}
});
});
describe('validateEnvAtBoot: the pre-migration snapshot switches', () => {
afterEach(() => {
vi.restoreAllMocks();
});
it('accepts a boolean switch and a keep count from 1 to 100', () => {
expect(() =>
validateEnvAtBoot({ TREK_DB_PRE_MIGRATE_SNAPSHOT: 'false', TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP: '100' }),
).not.toThrow();
});
it('refuses a misspelt switch instead of guessing which way the safety net should go', () => {
expect(bootReport({ TREK_DB_PRE_MIGRATE_SNAPSHOT: 'of' }).thrown).toMatch(/Invalid environment configuration/);
expect(bootReport({ TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP: '0' }).printed).toContain(
'TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP',
);
expect(bootReport({ TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP: '2.5' }).thrown).toMatch(
/Invalid environment configuration/,
);
});
});
describe('validateEnvAtBoot: the database engine', () => {
afterEach(() => {
vi.restoreAllMocks();
});
it('DB-BOOT-001: refuses a TREK_DB_URL that is not a postgres:// or postgresql:// URL, without printing it', () => {
for (const value of ['mysql://u:secret@db/trek', 'not a url', 'sqlite:///data/travel.db']) {
const { printed, thrown } = bootReport({ TREK_DB_URL: value });
expect(thrown, value).toMatch(/Invalid environment configuration/);
expect(printed, value).toContain('TREK_DB_URL=***');
expect(printed, value).not.toContain('secret');
}
});
it('DB-BOOT-002: masks TREK_DB_URL like every other secret', () => {
expect(SECRET_ENV_KEYS.has('TREK_DB_URL')).toBe(true);
});
it('DB-BOOT-003: refuses TREK_DB_URL together with a SQLite setting, naming both', () => {
for (const key of ['TREK_DB_FILE', 'TREK_DB_JOURNAL_MODE', 'TREK_DB_SYNCHRONOUS']) {
const { thrown, printed } = bootReport({ TREK_DB_URL: 'postgres://u:p@db/trek', [key]: 'x' });
expect(thrown, key).toMatch(/Invalid environment configuration/);
expect(printed, key).toContain('ambiguous database configuration');
expect(printed, key).toContain(key);
}
});
it('DB-BOOT-004: refuses a Postgres database while this release cannot run on one', () => {
const { thrown, printed } = bootReport({ TREK_DB_URL: 'postgresql://u:p@db:5432/trek?sslmode=require' });
expect(thrown).toMatch(/Invalid environment configuration/);
expect(printed).toContain('Postgres support is not complete in this release');
expect(printed).not.toContain('u:p@');
});
it('DB-BOOT-005: refuses a pool size outside 1 to 100', () => {
expect(bootReport({ TREK_DB_POOL_MAX: '0' }).thrown).toMatch(/Invalid environment configuration/);
expect(() => validateEnvAtBoot({ TREK_DB_POOL_MAX: '20' })).not.toThrow();
});
});