- v2: auth/signup, auth/login (+ code step, rate limited), PATCH /me; check-in look-up and scan returning an outcome for every normal result. Campus rule as v1. - Sign up/login/2FA/profile moved to src/services/auth.ts; scan preview and scan to src/services/checkin.ts. v1 answers unchanged (ServiceError v1Status). - Login, 2FA step, sign up and profile/password pages use v2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot
108 lines
4.0 KiB
TypeScript
108 lines
4.0 KiB
TypeScript
import type { Request, RequestHandler, Response, Router } from 'express';
|
|
import { z } from 'zod';
|
|
import { ApiError } from './errors';
|
|
import auth from '../middleware/authMiddleware';
|
|
|
|
/**
|
|
* Every /api/v2 endpoint is declared with `defineRoute`: method, path, who may call it, and zod
|
|
* schemas for the params, query, body and response. The same declaration
|
|
* - validates the request (400 VALIDATION_FAILED with per-field messages),
|
|
* - checks the response against its schema and strips anything it doesn't list (so a field
|
|
* can't leak by being added to a Prisma include), and
|
|
* - becomes the OpenAPI document (openapi.ts) — the docs can't drift from the code.
|
|
*/
|
|
|
|
export type Access = 'public' | 'optional' | 'user' | 'staff' | 'supervisor' | 'admin';
|
|
|
|
/** The signed-in person, as the auth middleware puts it on the request. */
|
|
export type ApiUser = { id: string; name: string; email: string; role: 'admin' | 'supervisor' | 'staff' | 'user' };
|
|
|
|
export type Ctx<P, Q, B> = {
|
|
params: P;
|
|
query: Q;
|
|
body: B;
|
|
user: ApiUser | null;
|
|
req: Request;
|
|
res: Response;
|
|
};
|
|
|
|
type Schema = z.ZodType;
|
|
type Infer<S> = S extends z.ZodType ? z.infer<S> : undefined;
|
|
|
|
export type RouteDef<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema> = {
|
|
method: 'get' | 'post' | 'put' | 'patch' | 'delete';
|
|
/** Express-style, relative to /api/v2: "/events/:id". */
|
|
path: string;
|
|
summary: string;
|
|
description?: string;
|
|
tag: string;
|
|
access: Access;
|
|
/**
|
|
* Staff and supervisor routes must say how they treat campus-scoped staff (see
|
|
* utils/campusScope.js and tests/campusScopeRoutes.test.js) — e.g. "scopeEvent(params.id)".
|
|
*/
|
|
campusScope?: string;
|
|
params?: P;
|
|
query?: Q;
|
|
body?: B;
|
|
response: R;
|
|
/** HTTP status on success (default 200). */
|
|
status?: number;
|
|
/** Runs after the access check, e.g. a rate limiter. */
|
|
middleware?: RequestHandler[];
|
|
handler: (ctx: Ctx<Infer<P>, Infer<Q>, Infer<B>>) => Promise<z.input<R>> | z.input<R>;
|
|
};
|
|
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
export type AnyRoute = RouteDef<any, any, any, any>;
|
|
|
|
export const routes: AnyRoute[] = [];
|
|
|
|
const ACCESS: Record<Access, RequestHandler[]> = {
|
|
public: [],
|
|
optional: [auth.optionalAuth],
|
|
user: [auth.protect],
|
|
staff: [auth.protect, auth.staff],
|
|
supervisor: [auth.protect, auth.supervisor],
|
|
admin: [auth.protect, auth.admin],
|
|
};
|
|
|
|
export function defineRoute<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema>(def: RouteDef<P, Q, B, R>): RouteDef<P, Q, B, R> {
|
|
if ((def.access === 'staff' || def.access === 'supervisor') && !def.campusScope) {
|
|
throw new Error(`${def.method.toUpperCase()} /api/v2${def.path}: staff and supervisor routes must declare campusScope`);
|
|
}
|
|
routes.push(def as AnyRoute);
|
|
return def;
|
|
}
|
|
|
|
const parse = <S extends Schema | undefined>(schema: S, value: unknown): Infer<S> =>
|
|
(schema ? schema.parse(value) : undefined) as Infer<S>;
|
|
|
|
/** Adds every defined route to the router. */
|
|
export function mount(router: Router, list: AnyRoute[] = routes): void {
|
|
for (const def of list) {
|
|
const run: RequestHandler = async (req, res, next) => {
|
|
try {
|
|
const ctx = {
|
|
params: parse(def.params, req.params),
|
|
query: parse(def.query, req.query),
|
|
body: parse(def.body, req.body ?? {}),
|
|
user: (req as Request & { user?: ApiUser }).user ?? null,
|
|
req,
|
|
res,
|
|
};
|
|
const result = await def.handler(ctx);
|
|
const checked = def.response.safeParse(result);
|
|
if (!checked.success) {
|
|
console.error(`[api/v2] ${def.method.toUpperCase()} ${def.path}: response doesn't match its schema`, checked.error.issues);
|
|
throw new ApiError('INTERNAL', 'Something went wrong on the server.');
|
|
}
|
|
res.status(def.status ?? 200).json(checked.data);
|
|
} catch (err) {
|
|
next(err);
|
|
}
|
|
};
|
|
router[def.method](def.path, ...ACCESS[def.access], ...(def.middleware ?? []), run);
|
|
}
|
|
}
|