feat: zod-backed input validation (#12)

Author: CryptoJones

app/middleware/validate.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+"use strict";
+
+const { ZodError } = require('zod');
+
+/**
+ * Express middleware factory: validate.body(schema) / validate.query(schema)
+ * / validate.params(schema). On parse failure, responds 400 with a
+ * structured error listing every invalid field. On success, replaces
+ * req.body / req.query / req.params with the parsed (coerced + stripped)
+ * value so controllers see only whitelisted fields.
+ *
+ * Why this lives at the middleware boundary rather than inside each
+ * controller:
+ *   - Centralizes the body-whitelist defense (controllers had
+ *     hand-rolled ALLOWED_FIELDS arrays — easy to drift).
+ *   - Surfaces parse errors as 400 with field-level detail before
+ *     they reach Sequelize, which would otherwise emit confusing
+ *     "value too long for type character varying(...)"-style 500s.
+ *   - Coerces "1" → 1 for path/query int params consistently.
+ */
+
+function fmt(err) {
+    if (err instanceof ZodError) {
+        // Zod 4 exposes `.issues`; older v3 exposed `.errors`. Accept
+        // both so the formatter works across zod major bumps.
+        const list = err.issues || err.errors || [];
+        return {
+            message: 'Validation failed.',
+            issues: list.map((e) => ({
+                path: Array.isArray(e.path) ? e.path.join('.') : String(e.path || ''),
+                code: e.code,
+                message: e.message,
+            })),
+        };
+    }
+    return { message: 'Validation failed.', error: String(err) };
+}
+
+function validateOn(key) {
+    return (schema) => (req, res, next) => {
+        const result = schema.safeParse(req[key]);
+        if (!result.success) {
+            return res.status(400).json(fmt(result.error));
+        }
+        req[key] = result.data;
+        return next();
+    };
+}
+
+module.exports = {
+    body: validateOn('body'),
+    query: validateOn('query'),
+    params: validateOn('params'),
+};

app/routers/router.js

@@ -9,6 +9,9 @@ const customer = require('../controllers/customercontroller.js');
 const health = require('../controllers/healthcontroller.js');
 const timeEntry = require('../controllers/timeentrycontroller.js');
 const openapiSpec = require('../config/openapi.js');
+const v = require('../middleware/validate.js');
+const customerSchemas = require('../schemas/customer.schema.js');
+const timeEntrySchemas = require('../schemas/timeentry.schema.js');
 
 // Health / readiness probe. No auth required — only exposes liveness
 // of the API process and reachability of the database.
@@ -24,15 +27,50 @@ router.use('/docs', swaggerUi.serve, swaggerUi.setup(openapiSpec, {
 }));
 
 // v1 customer routes.
-router.get('/v1/customer/:id', customer.getCustomerById);
-router.get('/v1/customer/bycompany/:id', customer.getAllByCompanyId);
-router.post('/v1/customer', customer.createCustomer);
+router.get(
+    '/v1/customer/:id',
+    v.params(customerSchemas.intIdParam),
+    customer.getCustomerById,
+);
+router.get(
+    '/v1/customer/bycompany/:id',
+    v.params(customerSchemas.intIdParam),
+    v.query(customerSchemas.listByCompanyQuery),
+    customer.getAllByCompanyId,
+);
+router.post(
+    '/v1/customer',
+    v.body(customerSchemas.createCustomerBody),
+    customer.createCustomer,
+);
 
 // v1 time-entry routes.
-router.post('/v1/timeentry', timeEntry.create);
-router.get('/v1/timeentry/bycompany/:id', timeEntry.listByCompany);
-router.get('/v1/timeentry/:id', timeEntry.getById);
-router.patch('/v1/timeentry/:id', timeEntry.update);
-router.delete('/v1/timeentry/:id', timeEntry.remove);
+router.post(
+    '/v1/timeentry',
+    v.body(timeEntrySchemas.createTimeEntryBody),
+    timeEntry.create,
+);
+router.get(
+    '/v1/timeentry/bycompany/:id',
+    v.params(timeEntrySchemas.intIdParam),
+    v.query(timeEntrySchemas.listByCompanyQuery),
+    timeEntry.listByCompany,
+);
+router.get(
+    '/v1/timeentry/:id',
+    v.params(timeEntrySchemas.intIdParam),
+    timeEntry.getById,
+);
+router.patch(
+    '/v1/timeentry/:id',
+    v.params(timeEntrySchemas.intIdParam),
+    v.body(timeEntrySchemas.updateTimeEntryBody),
+    timeEntry.update,
+);
+router.delete(
+    '/v1/timeentry/:id',
+    v.params(timeEntrySchemas.intIdParam),
+    timeEntry.remove,
+);
 
 module.exports = router;

app/schemas/customer.schema.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+"use strict";
+
+const { z } = require('zod');
+
+const intIdParam = z.object({
+    id: z.coerce.number().int().positive(),
+});
+
+/**
+ * Body schema for POST /v1/customer.
+ *
+ * Whitelist semantics: any field not listed here is stripped via
+ * .strip() (zod's default). Server-managed fields (custId, custArch)
+ * are NOT accepted from the body at all.
+ *
+ * teCompId is optional here because the controller may default it
+ * to the authKey's owning company for non-master keys. Master keys
+ * must supply it; the controller enforces that separately so it
+ * can emit a 400 with the contextual message rather than a generic
+ * zod issue.
+ */
+const createCustomerBody = z.object({
+    custCompanyName: z.string().max(255).optional(),
+    custFName: z.string().max(255).optional(),
+    custLName: z.string().max(255).optional(),
+    custAddress1: z.string().max(255).optional(),
+    custAddress2: z.string().max(255).optional(),
+    custCity: z.string().max(255).optional(),
+    custState: z.string().max(255).optional(),
+    custZip: z.string().max(32).optional(),
+    custPhone: z.string().max(64).optional(),
+    custEmail: z.string().email().max(255).optional(),
+    custCompId: z.coerce.number().int().positive().optional(),
+}).strict({
+    message: 'Unexpected field in body. Whitelist: custCompanyName, custFName, custLName, custAddress1, custAddress2, custCity, custState, custZip, custPhone, custEmail, custCompId.',
+});
+
+const listByCompanyQuery = z.object({
+    limit: z.coerce.number().int().positive().max(500).optional(),
+    offset: z.coerce.number().int().nonnegative().optional(),
+}).strict({
+    message: 'Unexpected query parameter. Allowed: limit, offset.',
+});
+
+module.exports = {
+    intIdParam,
+    createCustomerBody,
+    listByCompanyQuery,
+};

app/schemas/timeentry.schema.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+"use strict";
+
+const { z } = require('zod');
+
+const intIdParam = z.object({
+    id: z.coerce.number().int().positive(),
+});
+
+const isoDatetime = z.string().datetime({
+    offset: true,
+    message: 'Must be an ISO 8601 datetime (e.g. 2026-05-16T09:00:00Z).',
+});
+
+/**
+ * POST /v1/timeentry body. teCompId is optional for non-master keys
+ * (defaults to authKey's company) and required for master keys
+ * (controller enforces). teCustId + teStartedAt are required;
+ * teEndedAt is optional (in-flight entries allowed).
+ *
+ * Server-managed fields (teId, teMinutes, teArch) are not accepted
+ * from the body.
+ */
+const createTimeEntryBody = z.object({
+    teCustId: z.coerce.number().int().positive(),
+    teCompId: z.coerce.number().int().positive().optional(),
+    teDescription: z.string().max(10000).optional(),
+    teStartedAt: isoDatetime,
+    teEndedAt: isoDatetime.optional(),
+    teBillable: z.boolean().optional(),
+}).strict({
+    message: 'Unexpected field in body. Whitelist: teCustId, teCompId, teDescription, teStartedAt, teEndedAt, teBillable.',
+});
+
+/**
+ * PATCH /v1/timeentry/:id body. None of the fields are required —
+ * a PATCH is a partial update — but at least one must be present.
+ * The controller already handles the "no updatable fields" case
+ * with a 400; the schema just enforces shape.
+ */
+const updateTimeEntryBody = z.object({
+    teDescription: z.string().max(10000).optional(),
+    teStartedAt: isoDatetime.optional(),
+    teEndedAt: isoDatetime.nullable().optional(),
+    teBillable: z.boolean().optional(),
+}).strict({
+    message: 'Unexpected field in body. Whitelist: teDescription, teStartedAt, teEndedAt, teBillable.',
+});
+
+const listByCompanyQuery = z.object({
+    customerId: z.coerce.number().int().positive().optional(),
+    from: isoDatetime.optional(),
+    to: isoDatetime.optional(),
+    limit: z.coerce.number().int().positive().max(500).optional(),
+    offset: z.coerce.number().int().nonnegative().optional(),
+}).strict({
+    message: 'Unexpected query parameter. Allowed: customerId, from, to, limit, offset.',
+});
+
+module.exports = {
+    intIdParam,
+    createTimeEntryBody,
+    updateTimeEntryBody,
+    listByCompanyQuery,
+};

package-lock.json

@@ -31,7 +31,8 @@
     "pino-http": "^11.0.0",
     "sequelize": "^6.6.5",
     "sequelize-cli": "^6.2.0",
-    "swagger-ui-express": "^5.0.1"
+    "swagger-ui-express": "^5.0.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "supertest": "^7.2.2",