Phase 0 — NestJS + Zod foundation harness (F1–F8) (#1050)

Co-hosted NestJS app behind the existing Express server via a strangler-fig dispatcher, sharing the same better-sqlite3 connection and JWT httpOnly cookie. Additive and dormant: default routing stays on Express, Nest only serves its own /api/_nest diagnostics until a module opts in.

F1 @trek/shared Zod contract package; F2 Nest bootstrap co-hosted (fall-through, single Dockerfile/port); F3 shared better-sqlite3 provider; F4 JWT cookie auth guard (+ @CurrentUser, admin guard); F5 Zod validation pipe + error-envelope parity; F6 Nest test + coverage gates; F7 per-prefix strangler toggle (env, default Express); F8 CI build/typecheck/test/coverage.

Remaining F4/F6/F8 checklist items (trip-access + permission levels + MFA policy, e2e harness/seed + 80% gate, Nest↔Express parity test, Playwright PR-comment workflow) are tracked on the first consuming module cards (L1/A1/C1).

server/src/nest/app.module.ts

@@ -0,0 +1,22 @@
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+import { DatabaseModule } from './database/database.module';
+import { HealthController } from './health/health.controller';
+import { HealthService } from './health/health.service';
+import { TrekExceptionFilter } from './common/trek-exception.filter';
+
+/**
+ * Root NestJS module for the incremental migration. Domain modules
+ * (weather, notifications, ...) get registered here as they are migrated.
+ */
+@Module({
+  imports: [DatabaseModule],
+  controllers: [HealthController],
+  providers: [
+    HealthService,
+    // Global error-envelope normaliser (DI-registered so it also catches
+    // framework-level exceptions like the not-found handler).
+    { provide: APP_FILTER, useClass: TrekExceptionFilter },
+  ],
+})
+export class AppModule {}

server/src/nest/auth/admin.guard.ts

@@ -0,0 +1,19 @@
+import { CanActivate, ExecutionContext, HttpException, Injectable } from '@nestjs/common';
+import type { Request } from 'express';
+import type { User } from '../../types';
+
+/**
+ * Mirrors the legacy `adminOnly` middleware: requires an authenticated admin.
+ * Use together with JwtAuthGuard (which populates req.user):
+ * `@UseGuards(JwtAuthGuard, AdminGuard)`.
+ */
+@Injectable()
+export class AdminGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request & { user?: User }>();
+    if (!req.user || req.user.role !== 'admin') {
+      throw new HttpException({ error: 'Admin access required' }, 403);
+    }
+    return true;
+  }
+}

server/src/nest/auth/current-user.decorator.ts

@@ -0,0 +1,12 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { User } from '../../types';
+
+/**
+ * Resolves the authenticated user attached by JwtAuthGuard.
+ * Use on guarded handlers: `getThing(@CurrentUser() user: User) { ... }`.
+ */
+export const CurrentUser = createParamDecorator(
+  (_data: unknown, context: ExecutionContext): User | undefined => {
+    return context.switchToHttp().getRequest().user;
+  },
+);

server/src/nest/auth/jwt-auth.guard.ts

@@ -0,0 +1,28 @@
+import { CanActivate, ExecutionContext, HttpException, Injectable } from '@nestjs/common';
+import type { Request } from 'express';
+import { extractToken, verifyJwtAndLoadUser } from '../../middleware/auth';
+
+/**
+ * Validates TREK's existing JWT session — the same httpOnly `trek_session`
+ * cookie (or `Authorization: Bearer`) the legacy app uses. Reuses the canonical
+ * `verifyJwtAndLoadUser` so the secret, the password_version invalidation gate
+ * and the loaded user are IDENTICAL to the Express middleware. No new tokens.
+ *
+ * Error bodies match the legacy 401 shape exactly so the client is unaffected.
+ */
+@Injectable()
+export class JwtAuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request>();
+    const token = extractToken(req);
+    if (!token) {
+      throw new HttpException({ error: 'Access token required', code: 'AUTH_REQUIRED' }, 401);
+    }
+    const user = verifyJwtAndLoadUser(token);
+    if (!user) {
+      throw new HttpException({ error: 'Invalid or expired token', code: 'AUTH_REQUIRED' }, 401);
+    }
+    (req as Request & { user?: unknown }).user = user;
+    return true;
+  }
+}

server/src/nest/common/trek-exception.filter.ts

@@ -0,0 +1,42 @@
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
+import type { Response } from 'express';
+
+/**
+ * Normalises every Nest exception to TREK's legacy error envelope so migrated
+ * routes are byte-identical for the client:
+ *   - 4xx -> { error: <message> }   (5xx -> { error: 'Internal server error' })
+ *   - exceptions already throwing { error, code? } (e.g. the auth guards) pass through
+ * This replaces Nest's default { statusCode, message, error } body, which the
+ * TREK client does not expect.
+ */
+@Catch()
+export class TrekExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const res = host.switchToHttp().getResponse<Response>();
+
+    if (exception instanceof HttpException) {
+      const status = exception.getStatus();
+      const body = exception.getResponse();
+
+      // Already in TREK shape (e.g. guards throw { error, code }): pass through.
+      if (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)) {
+        res.status(status).json(body);
+        return;
+      }
+
+      const raw = typeof body === 'string' ? body : (body as { message?: unknown })?.message;
+      const message =
+        status < 500
+          ? Array.isArray(raw)
+            ? raw.join(', ')
+            : String(raw ?? 'Error')
+          : 'Internal server error';
+      res.status(status).json({ error: message });
+      return;
+    }
+
+    // Unknown/unhandled error — mirror the legacy 500 behaviour.
+    console.error('Unhandled error:', exception);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+}

server/src/nest/common/zod-validation.pipe.ts

@@ -0,0 +1,26 @@
+import { ArgumentMetadata, HttpException, Injectable, PipeTransform } from '@nestjs/common';
+import type { ZodType } from 'zod';
+
+/**
+ * Validates an incoming @Body()/@Query() against a Zod schema (from @trek/shared)
+ * and returns the parsed, typed value. On failure it throws TREK's error envelope
+ * `{ error: string }` with status 400 — the same shape the legacy routes produce,
+ * so the client's error handling is unaffected.
+ *
+ * Usage: `@Body(new ZodValidationPipe(someSchema)) dto: Dto`.
+ */
+@Injectable()
+export class ZodValidationPipe implements PipeTransform {
+  constructor(private readonly schema: ZodType) {}
+
+  transform(value: unknown, _metadata: ArgumentMetadata): unknown {
+    const result = this.schema.safeParse(value);
+    if (!result.success) {
+      const message = result.error.issues
+        .map((i) => `${i.path.join('.') || 'body'}: ${i.message}`)
+        .join('; ');
+      throw new HttpException({ error: message }, 400);
+    }
+    return result.data;
+  }
+}

server/src/nest/database/database.module.ts

@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { DatabaseService } from './database.service';
+
+/**
+ * Global so every migrated module can inject DatabaseService without re-importing.
+ * Wraps the existing better-sqlite3 singleton (no new connection).
+ */
+@Global()
+@Module({
+  providers: [DatabaseService],
+  exports: [DatabaseService],
+})
+export class DatabaseModule {}

server/src/nest/database/database.service.ts

@@ -0,0 +1,39 @@
+import { Injectable } from '@nestjs/common';
+import type Database from 'better-sqlite3';
+import { db } from '../../db/database';
+
+/**
+ * Injectable wrapper around TREK's existing better-sqlite3 connection.
+ *
+ * `db` is a Proxy onto the singleton connection the legacy app already uses
+ * (WAL enabled), so Nest modules share the exact same connection — no second
+ * connection, no split state, single writer preserved.
+ */
+@Injectable()
+export class DatabaseService {
+  /** The shared better-sqlite3 connection (same singleton the legacy app uses). */
+  get connection(): Database.Database {
+    return db;
+  }
+
+  prepare(sql: string): Database.Statement {
+    return db.prepare(sql);
+  }
+
+  get<T = unknown>(sql: string, ...params: unknown[]): T | undefined {
+    return db.prepare(sql).get(...params) as T | undefined;
+  }
+
+  all<T = unknown>(sql: string, ...params: unknown[]): T[] {
+    return db.prepare(sql).all(...params) as T[];
+  }
+
+  run(sql: string, ...params: unknown[]): Database.RunResult {
+    return db.prepare(sql).run(...params);
+  }
+
+  /** Run `fn` inside a synchronous better-sqlite3 transaction. */
+  transaction<T>(fn: (conn: Database.Database) => T): T {
+    return db.transaction(() => fn(db))();
+  }
+}

server/src/nest/health/health.controller.ts

@@ -0,0 +1,41 @@
+import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
+import { z } from 'zod';
+import type { User } from '../../types';
+import { HealthService } from './health.service';
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { CurrentUser } from '../auth/current-user.decorator';
+import { ZodValidationPipe } from '../common/zod-validation.pipe';
+
+// Local demo schema (real domains import their schema from @trek/shared).
+const echoSchema = z.object({ name: z.string().min(1) });
+
+/**
+ * Foundation smoke endpoints for the co-hosted NestJS app.
+ * Proves: boot, routing, type-based DI, the shared SQLite connection, the
+ * JWT-cookie auth guard, and the Zod validation pipe + error-envelope parity.
+ *
+ * Lives under /api/_nest/* so it never collides with the legacy Express API.
+ */
+@Controller('api/_nest')
+export class HealthController {
+  constructor(private readonly healthService: HealthService) {}
+
+  @Get('health')
+  getHealth() {
+    return { ok: true, ...this.healthService.info() };
+  }
+
+  /** Guarded: returns the authenticated user, proving JwtAuthGuard + @CurrentUser. */
+  @Get('me')
+  @UseGuards(JwtAuthGuard)
+  me(@CurrentUser() user: User) {
+    return user;
+  }
+
+  /** Validated: proves the Zod pipe (400 + { error } on failure) and body parsing. */
+  @Post('echo')
+  @UseGuards(JwtAuthGuard)
+  echo(@Body(new ZodValidationPipe(echoSchema)) body: z.infer<typeof echoSchema>) {
+    return { youSent: body };
+  }
+}

server/src/nest/health/health.service.ts

@@ -0,0 +1,21 @@
+import { Injectable } from '@nestjs/common';
+import { DatabaseService } from '../database/database.service';
+
+/**
+ * Smoke service proving NestJS DI works under the chosen runtime AND that the
+ * injected DatabaseService talks to TREK's existing SQLite connection.
+ */
+@Injectable()
+export class HealthService {
+  constructor(private readonly database: DatabaseService) {}
+
+  info() {
+    const row = this.database.get<{ n: number }>('SELECT COUNT(*) AS n FROM users');
+    return {
+      runtime: 'nestjs',
+      diInjected: true,
+      // Proof the shared connection works: real row count from the existing DB.
+      userCount: row?.n ?? null,
+    };
+  }
+}

server/src/nest/strangler.ts

@@ -0,0 +1,24 @@
+/**
+ * Strangler toggle for the incremental NestJS migration.
+ *
+ * `getNestPrefixes()` returns the request path prefixes that NestJS handles;
+ * every other path falls through to the legacy Express app. The default is the
+ * set of prefixes whose Nest modules exist. Operators can override it at runtime
+ * via the `NEST_PREFIXES` env var (comma-separated) for instant Nest<->Express
+ * rollback — no redeploy, no code change. Setting `NEST_PREFIXES=` (empty) routes
+ * everything back to the legacy app.
+ */
+const DEFAULT_NEST_PREFIXES = ['/api/_nest'];
+
+export function getNestPrefixes(): string[] {
+  const raw = process.env.NEST_PREFIXES;
+  if (raw !== undefined) {
+    return raw.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return DEFAULT_NEST_PREFIXES;
+}
+
+/** Builds a matcher: true when `path` belongs to one of the migrated prefixes. */
+export function makeNestPathMatcher(prefixes: string[]): (path: string) => boolean {
+  return (path) => prefixes.some((prefix) => path === prefix || path.startsWith(prefix + '/'));
+}