fix(validation): ZodEffects unknown-keys engine, abortEarly, SSRF guard

[frankstupak]

Validation: the unknown-keys engine was a no-op for half the schemas — plus 4.5x/25x speedups

The npm install in src/api/validation doesn't even complete (fastify-zod@1.4.0 peers fastify@^4 against the fastify@5, and it isn't imported anywhere), so let's start there and work up.

Broken install

• Removed the unused fastify-zod dependency that hard-fails dependency resolution.
• Added @fastify/swagger — server.ts imports it, package.json never declared it.
• fastify-plugin 4 → 5 to match Fastify 5.

The unknown-keys engine didn't do what it says

Three compounding bugs, all with regression tests:

1. ZodEffects bypass. stripUnknown / allowUnknown / strict all hinge on schema instanceof z.ZodObject. Any schema with .refine() or .transform() is a ZodEffects — including the existing UserSchemas.registration — so every unknown-keys option was a silent no-op for exactly the schemas most worth protecting. The engine now unwraps effects recursively and rebuilds the wrapper around the configured inner object.
2. .strict() silently downgraded. profileUpdate is declared .strict() with the comment "Prevent unknown fields". The engine's default stripUnknown: true replaced it with .strip(), so unknown keys were quietly accepted on the one schema that explicitly forbade them. Engine defaults no longer weaken an author's .strict(); an explicit caller option still can.
3. { allowUnknown: true } alone was ignored. The if-chain checked stripUnknown first, and the default is true, so passing only allowUnknown did nothing. Precedence is now allowUnknown > stripUnknown > strict.

Also: abortEarly was decorative. Both branches ran complete validation (safeParseAsync vs parseAsync — identical issue lists; Zod v3 has no mid-parse abort). The option is now honored where callers can actually observe it: the error payload carries exactly the first issue.

Performance

Single validate: 115k → 550k ops/s (~4.5–4.8x) on a typical request schema.

single-validate throughput (sync object schema, stripUnknown default, 200,000 iters):
  original: 1731ms = 115,544 ops/s
  uplifted:  363ms = 550,307 ops/s   -> 4.76x

Two changes: (a) a one-time static walk of the schema tree decides whether it can possibly do async work; provably-sync schemas (params, query, pagination — the hot path) go through safeParse and skip the per-call setTimeout + Promise.race + microtask machinery entirely; (b) configured schema variants (.strip()/.strict()/.passthrough() each allocate a whole new schema) are cached in a WeakMap instead of rebuilt on every request.

Why static analysis and not runtime probing: calling safeParse on an async schema makes Zod start the refinement, then throw and abandon its promise — if that orphaned promise rejects, the process dies with an unhandled rejection (Node 15+). Verified empirically against zod 3.25, including zod's own ~standard.validate wrapper which probes sync-first and has the same hazard. There's a regression test asserting no unhandled rejection when an async refinement fails after the timeout fires.

Batch with async refinements: 1059ms → 42ms (25.4x). validateBatch serialized every item — item N+1's DB-lookup refinement couldn't start until item N's finished. It now takes opt-in concurrency ({ concurrency: 32 }) with index-stable results and error fields. Default remains sequential; zero behavior change unless opted in.

batch 200 items x 5ms async refine:
  original (sequential):      1059ms
  uplifted (concurrency=32):    42ms  -> 25.4x

bench.ts + the frozen original engine (bench-original-engine.ts) are included — npx tsx bench.ts reproduces every number above.

Schema correctness

• Email: .toLowerCase().trim() ran after .email() (Zod applies string checks in chain order), so " User@Example.com " — the input the normalizers exist for — was rejected. Normalizers now run first.
• Price range falsy-zero bypass: if (data.priceMin && data.priceMax) skips the check when either bound is 0 (prices are in cents; 0 is legal). priceMin=500, priceMax=0 validated successfully. Now != null.
• Timezone regex rejected most of the real IANA database: ^[A-Za-z_]+/[A-Za-z_]+$ fails America/Argentina/Buenos_Aires, UTC, and Etc/GMT+8 while accepting Foo/Bar. Replaced with an Intl.DateTimeFormat check against the runtime's actual tz database.
• fileUpload accepted ., .., and trailing dots/spaces — traversal primitives and Windows-hostile names that the character allowlist alone doesn't catch.
• Webhook SSRF: user-supplied URLs the servers will fetch accepted https://localhost/, https://169.254.169.254/ (cloud metadata), and all of RFC1918. Now rejected (loopback, private, link-local, CGNAT, and IPv6 equivalents), with the DNS-rebinding caveat documented for the HTTP client layer.
• dateOfBirth required a full ISO datetime — "1990-05-10" was invalid. Now accepts date-only or datetime, and the age check is calendar-accurate instead of elapsed / 365.25, which drifts by up to a day around birthdays (someone turning 13 today could be rejected).
• requireContentType used substring matching: application/jsonx passed for application/json. Now compares the parsed media type exactly (parameters like charset still stripped).
• validateData/validateBatch wrappers silently dropped the context param; engine signatures now accept transforming schemas (ZodType<T, Def, unknown>), which is why registration could never be run through the engine's own typed API before.

Verification

• 37/37 tests green (the original 21 untouched + 16 new regressions), tsc --noEmit clean, eslint clean.
• Root npm run test:all: validation suite passes; the pre-existing failures on main (nextjs-backend ×4, autocomplete, api-scenarios) are untouched — this diff is confined to src/api/validation/.

Public API is backward compatible: every previously-passing call still passes with the same shape; the behavior deltas are exactly the documented bugs above.

— Lumen Industries