Nicolas
3a5dc83bf9
Five more explicit review points, on the same PR branch. ## Every interface key commented Audited all 6 interfaces in the codebase. Two had partially-commented members (violates the "every key gets /** */" rule): AuthResult (apps/api/auth.service.ts) and SafeUserProfile (packages/shared) — both now fully commented. The other four (AuthTokenPayload, AuthContextValue, ErrorHandlingResult, ApiErrorResponse) were already compliant. ## Removed the Express namespace augmentation apps/api/src/types/express.d.ts (renamed to express-request.augment.ts in the last round) is gone entirely. requireAuth now attaches the authenticated profile to `res.locals.userProfile` — Express's own built-in per-request mechanism for exactly this — typed via a new AuthLocals interface and `Response<unknown, AuthLocals>`, instead of a project-wide `declare global` silently changing every Request's type whether or not it went through the middleware. ## ErrorHandlerService confirmed framework-agnostic It already had zero Express import. Documented this explicitly (in the package's index.ts and the new backend-architecture.md spec) as a deliberate split: ErrorHandlerService is framework-agnostic (would work behind Fastify too), ExpressServer/createErrorMiddleware are the actual Express integration layer. ## packages/express-tools: server init + route/middleware utilities New ExpressServer class, modeled on the pattern shared as a reference (adapted, not copied 1:1 — deliberately left out the reference's custom runtime param-type-validation system, since zod already does that job in this codebase and running two parallel validation mechanisms would be redundant, not "propre"): - setupCore() — the common cors/json/cookie-parser stack - addRoute() — registers a route, warns+skips instead of silently double-registering the same method+path - addMiddleware() / mountRouter() / setErrorHandler() - listen() - .instance — the raw Express app, for supertest Also added wrapAsyncHandler() — forwards a thrown/rejected error from an async handler to next(err) automatically, removing the manual try/catch/next(err) every route needed. apps/api/src/app.ts now builds via ExpressServer (createServer(), consumed by both server.ts's .listen() and createApp()'s .instance for tests). auth.routes.ts's signup/login handlers use wrapAsyncHandler instead of manual try/catch. cookie-parser/cors moved out of apps/api's own dependencies entirely — they're express-tools' concern now. ## assertIsNever (packages/shared/src/tools/) Exhaustiveness-check helper for switch/if-chains over a union: takes a `never`-typed value and throws, so a forgotten case in a later-added union member becomes a compile error instead of a silent runtime fallthrough. Verified for real (not just written and assumed correct): wrote a throwaway switch missing a case and confirmed `tsc` rejects it with the exact expected error, then deleted the scratch file. No existing switch/if-chain over a union in the codebase yet to retrofit it into — noted as ready for when one appears (e.g. the not-yet-built batch-cooking calculation module or recipe-import pipeline). ## specs/ updated New specs/backend-architecture.md — ExpressServer, wrapAsyncHandler, the res.locals decision (with the "why not declare global" reasoning spelled out), assertIsNever. error-handling.md and frontend-architecture.md cross-link to it instead of duplicating. README covers the same, briefly. ## Verification Full lint/mocha/cucumber/build green. Re-ran `node dist/server.js` standalone (mirrors Docker, no tsx) after the ExpressServer refactor: /health, a 404 (numeric 4040), and a real signup + GET /me round trip confirming res.locals-based auth actually works at runtime, not just that tsc accepts the types.
68 lines
2.8 KiB
TypeScript
68 lines
2.8 KiB
TypeScript
import { HttpError } from "@batch-cooking/express-tools";
|
|
import { ErrorCode, type SafeUserProfile } from "@batch-cooking/shared";
|
|
import type { NextFunction, Request, Response } from "express";
|
|
import { env } from "../config/env.js";
|
|
import { prisma } from "../db/prisma.js";
|
|
import { verifyAuthToken } from "../lib/jwt.js";
|
|
|
|
/**
|
|
* Shape of `res.locals` once {@link requireAuth} has run successfully. Type
|
|
* a route handler's response as `Response<unknown, AuthLocals>` (see
|
|
* `auth.routes.ts`'s `/me` handler) to read `res.locals.userProfile` fully
|
|
* typed, no cast needed.
|
|
*/
|
|
export interface AuthLocals {
|
|
/** The authenticated profile, resolved from the session cookie's JWT. */
|
|
userProfile: SafeUserProfile;
|
|
}
|
|
|
|
/**
|
|
* Express middleware guarding routes that require an authenticated
|
|
* profile. Reads the session cookie, verifies the JWT, and re-checks
|
|
* `tokenVersion` against the database — so a stateless JWT can still be
|
|
* invalidated server-side (e.g. on password change / logout-everywhere,
|
|
* once that feature exists) despite carrying no server-side session.
|
|
*
|
|
* On success, attaches the resolved profile to `res.locals.userProfile`
|
|
* (typed via {@link AuthLocals}) for downstream handlers to use.
|
|
* Deliberately `res.locals` rather than augmenting Express's global
|
|
* `Request` type via `declare global`: `res.locals` is Express's own
|
|
* built-in mechanism for exactly this (passing data from a middleware to
|
|
* the next handler), typed per-route through a generic parameter — no
|
|
* project-wide ambient augmentation silently changing every `Request` in
|
|
* the codebase, whether or not it went through this middleware.
|
|
*
|
|
* @throws {HttpError} `401 NOT_AUTHENTICATED` for any failure — missing
|
|
* cookie, malformed/expired JWT, unknown profile, or stale tokenVersion.
|
|
* Never distinguishes the reason to the client.
|
|
*/
|
|
export async function requireAuth(
|
|
req: Request,
|
|
res: Response<unknown, AuthLocals>,
|
|
next: NextFunction,
|
|
) {
|
|
try {
|
|
const token = req.cookies?.[env.AUTH_COOKIE_NAME];
|
|
if (typeof token !== "string") {
|
|
throw new HttpError(401, ErrorCode.NOT_AUTHENTICATED, "Not authenticated");
|
|
}
|
|
|
|
const payload = verifyAuthToken(token);
|
|
const profile = await prisma.userProfile.findUnique({ where: { id: payload.userProfileId } });
|
|
|
|
if (!profile || profile.tokenVersion !== payload.tokenVersion) {
|
|
throw new HttpError(401, ErrorCode.NOT_AUTHENTICATED, "Not authenticated");
|
|
}
|
|
|
|
const { passwordHash: _passwordHash, ...safeProfile } = profile;
|
|
res.locals.userProfile = safeProfile;
|
|
next();
|
|
} catch (err) {
|
|
if (err instanceof HttpError) {
|
|
next(err);
|
|
} else {
|
|
// Covers jwt.verify failures (expired/invalid/malformed token).
|
|
next(new HttpError(401, ErrorCode.NOT_AUTHENTICATED, "Not authenticated"));
|
|
}
|
|
}
|
|
}
|