@warlock.js/core 5.2.4 → 5.3.0

package/skills/create-controller/SKILL.md

@@ -12,7 +12,7 @@ A controller is a thin function: pull inputs from `request`, call work, return t
 ```ts title="src/app/<module>/controllers/<action>.controller.ts"
 import { type RequestHandler } from "@warlock.js/core";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   return response.success({ products: [] });
 };
 ```
@@ -67,10 +67,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -96,10 +96,10 @@ Routes behind `authMiddleware` need `request.user` typed. Project conventions ad
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   // request.user is typed
   const product = await createProductService(request.validated());
   return response.successCreate({ product });
@@ -146,7 +146,7 @@ If your controller is over ~30 lines, the work probably belongs in a service.
 import { type RequestHandler } from "@warlock.js/core";
 import { listProductsService } from "../services/list-products.service";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   const { data: products, pagination } = await listProductsService({
     ...request.all(),
     organization_id: request.user.organizationId,
@@ -163,10 +163,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -200,7 +200,7 @@ export async function getProductService(id: string) {
 import type { RequestHandler } from "@warlock.js/core";
 import { getProductService } from "../services/get-product.service";
 
-export const getProductController: RequestHandler = async (request, response) => {
+export const getProductController: RequestHandler = async ({ request, response }) => {
   const product = await getProductService(request.input("id"));
 
   return response.success({ product });

package/skills/send-response/SKILL.md

@@ -10,9 +10,9 @@ description: 'Send HTTP responses via @warlock.js/core''s Response helpers — s
 ## The shape
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import type { RequestHandler } from "@warlock.js/core";
 
-export const myController: RequestHandler = async (request, response: Response) => {
+export const myController: RequestHandler = async ({ request, response }) => {
   // …choose a helper and return it
   return response.success({ data: "…" });
 };
@@ -22,11 +22,11 @@ Always `return response.<helper>(...)`. The return value drives Fastify's send.
 
 ## Success helpers
 
-| Method                              | Status | When                                      |
-| ----------------------------------- | ------ | ----------------------------------------- |
-| `response.success(data?)`           | 200    | normal read / update                      |
-| `response.successCreate(data)`      | 201    | resource created (POST)                   |
-| `response.noContent()`              | 204    | delete succeeded, no body needed          |
+| Method                         | Status | When                             |
+| ------------------------------ | ------ | -------------------------------- |
+| `response.success(data?)`      | 200    | normal read / update             |
+| `response.successCreate(data)` | 201    | resource created (POST)          |
+| `response.noContent()`         | 204    | delete succeeded, no body needed |
 
 ```ts
 return response.success({ products: [...] });
@@ -40,13 +40,13 @@ return response.noContent();
 
 ## Client-error helpers
 
-| Method                                              | Status | When                                  |
-| --------------------------------------------------- | ------ | ------------------------------------- |
-| `response.badRequest(data)`                         | 400    | malformed or invalid input            |
-| `response.unauthorized(data?)`                      | 401    | missing/invalid auth token            |
-| `response.forbidden(data?)`                         | 403    | authenticated but not allowed         |
-| `response.notFound(data?)`                          | 404    | record missing                        |
-| `response.conflict(data?)`                          | 409    | uniqueness violation, state conflict  |
+| Method                         | Status | When                                 |
+| ------------------------------ | ------ | ------------------------------------ |
+| `response.badRequest(data)`    | 400    | malformed or invalid input           |
+| `response.unauthorized(data?)` | 401    | missing/invalid auth token           |
+| `response.forbidden(data?)`    | 403    | authenticated but not allowed        |
+| `response.notFound(data?)`     | 404    | record missing                       |
+| `response.conflict(data?)`     | 409    | uniqueness violation, state conflict |
 
 ```ts
 return response.badRequest({ error: t("validation.invalid") });
@@ -65,8 +65,8 @@ Most error helpers accept an optional payload — if you omit it, they send a de
 ## Redirects
 
 ```ts
-return response.redirect("/login");                    // 302
-return response.redirect("/new-home", 301);            // permanent
+return response.redirect("/login"); // 302
+return response.redirect("/new-home", 301); // permanent
 ```
 
 ## Files
@@ -98,19 +98,19 @@ stream.end();
 
 ## Throwing HTTP errors
 
-Most of the time, controllers don't need to *choose* an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
+Most of the time, controllers don't need to _choose_ an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
 
 ```ts
 import {
-  ResourceNotFoundError,   // 404
-  UnAuthorizedError,        // 401
-  ForbiddenError,           // 403
-  BadRequestError,          // 400
-  ConflictError,            // 409
-  NotAcceptableError,       // 406
-  NotAllowedError,          // 405
-  ServerError,              // 500
-  HttpError,                // base class — `new HttpError(status, message, payload?)` for arbitrary codes
+  ResourceNotFoundError, // 404
+  UnAuthorizedError, // 401
+  ForbiddenError, // 403
+  BadRequestError, // 400
+  ConflictError, // 409
+  NotAcceptableError, // 406
+  NotAllowedError, // 405
+  ServerError, // 500
+  HttpError, // base class — `new HttpError(status, message, payload?)` for arbitrary codes
 } from "@warlock.js/core";
 
 throw new ResourceNotFoundError("product.notFound");
@@ -118,13 +118,27 @@ throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
 ```
 
-Each class takes `(message, payload?)`. The payload merges into the response body alongside `error`. In development mode, the stack trace is included too.
+Each class takes `(message, payload?)`. The framework keeps the optional
+detail nested under `payload`:
+
+```json
+{
+  "error": "Product not found",
+  "payload": { "id": 42 }
+}
+```
+
+Every unhandled error response also carries
+`Cache-Control: private, no-store`, regardless of status. The floor is
+applied once at the shared error funnel, so API-route errors cannot be stored
+and replayed across users. In development mode, the stack trace is included
+too.
 
 Pick the class, throw from the service or use-case, and forget about response shaping at the call site. The controller stays focused on the success path:
 
 ```ts
-export const getProductController: RequestHandler = async (request, response) => {
-  const product = await getProductService(request.input("id"));   // throws ResourceNotFoundError on miss
+export const getProductController: RequestHandler = async ({ request, response }) => {
+  const product = await getProductService(request.input("id")); // throws ResourceNotFoundError on miss
   return response.success({ product });
 };
 ```
@@ -136,9 +150,9 @@ See [`create-controller`](../create-controller/SKILL.md) for the "throw from ser
 ```ts
 const sse = response.sse();
 
-sse.send("tick", { count: 1 });             // event name, data, optional id
-sse.send("tick", { count: 2 }, "msg-2");    // third arg is the SSE event id
-sse.comment("keep-alive");                  // invisible to the client, prevents timeout
+sse.send("tick", { count: 1 }); // event name, data, optional id
+sse.send("tick", { count: 2 }, "msg-2"); // third arg is the SSE event id
+sse.comment("keep-alive"); // invisible to the client, prevents timeout
 sse.end();
 ```
 
@@ -178,11 +192,11 @@ response.clearCookie("session_id");
 
 Every response cookie gets `httpOnly: true`, `sameSite: "lax"`, and `secure: true` outside development, unless you override them:
 
-| Flag | Default | Why it's the default |
-|---|---|---|
-| `httpOnly` | `true` | without it, any injected script can read the cookie |
-| `sameSite` | `"lax"` | without it, the cookie rides along on cross-site requests |
-| `secure` | `true`, except in development | without it, the cookie travels in cleartext |
+| Flag       | Default                       | Why it's the default                                      |
+| ---------- | ----------------------------- | --------------------------------------------------------- |
+| `httpOnly` | `true`                        | without it, any injected script can read the cookie       |
+| `sameSite` | `"lax"`                       | without it, the cookie rides along on cross-site requests |
+| `secure`   | `true`, except in development | without it, the cookie travels in cleartext               |
 
 `secure` is relaxed in development only — browsers drop a `Secure` cookie over plain http, which would silently break every local login. It stays on in test and staging.
 

package/skills/store-file/SKILL.md

@@ -345,12 +345,17 @@ Set `STORAGE_DRIVER=r2` in production, leave unset in dev — same code uses loc
 ### Uploading a request file
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { storage } from "@warlock.js/core";
 
-export const uploadAvatarController: RequestHandler = async (request, response: Response) => {
+export const uploadAvatarController: GuardedRequestHandler = async ({ request, response }) => {
   const upload = request.file("avatar");
-  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.fileName}`);
+
+  if (!upload) {
+    return response.badRequest({ error: "missing file" });
+  }
+
+  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.name}`);
 
   return response.successCreate({ url: file.url, hash: file.hash });
 };

package/skills/upload-file/SKILL.md

@@ -9,8 +9,8 @@ Multipart uploads come in as `UploadedFile` instances. The class wraps Fastify's
 
 ## The shape
 
-```ts title="src/app/uploads/schema/index.ts"
-import { v } from "@warlock.js/seal";
+```ts title="src/app/uploads/schema/upload-avatar.schema.ts"
+import { v, type Infer } from "@warlock.js/seal";
 
 export const uploadAvatarSchema = v.object({
   avatar: v
@@ -19,16 +19,18 @@ export const uploadAvatarSchema = v.object({
     .maxSize({ unit: "MB", size: 5 })
     .mimeType(["image/jpeg", "image/png", "image/webp"]),
 });
+
+export type UploadAvatarSchema = Infer<typeof uploadAvatarSchema>;
 ```
 
 ```ts title="src/app/uploads/controllers/upload-avatar.controller.ts"
-import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type UploadAvatarSchema, uploadAvatarSchema } from "../schema/upload-avatar.schema";
 
-export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async (
+export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const { avatar } = request.validated();
 
   const file = await avatar
@@ -54,7 +56,7 @@ Inside a controller:
 ```ts
 import type { RequestHandler, UploadedFile } from "@warlock.js/core";
 
-export const uploadController: RequestHandler = async (request, response) => {
+export const uploadController: RequestHandler = async ({ request, response }) => {
   // option A — direct from request, no validation
   const file: UploadedFile | undefined = request.file("avatar");
 
@@ -236,7 +238,7 @@ export const uploadFilesSchema = v.object({
 ```ts title="src/app/uploads/controllers/create-upload.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const createUploadController: RequestHandler = async (request, response) => {
+export const createUploadController: RequestHandler = async ({ request, response }) => {
   const { files } = request.validated();
 
   const saved = await Promise.all(

package/skills/use-app-context/SKILL.md

@@ -232,9 +232,9 @@ const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-
 ### Health endpoint
 
 ```ts title="src/app/system/controllers/health.controller.ts"
-import { Application, type RequestHandler, type Response } from "@warlock.js/core";
+import { Application, type RequestHandler } from "@warlock.js/core";
 
-export const healthController: RequestHandler = async (_request, response: Response) => {
+export const healthController: RequestHandler = async ({ response }) => {
   return response.success({
     status: "ok",
     environment: Application.environment,

package/skills/use-localization/SKILL.md

@@ -229,10 +229,14 @@ The error's message is locale-aware — the `inject-request-context` middleware
 ### Translated response message in a controller
 
 ```ts
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { type CreateProductSchema } from "../schema/create-product.schema";
+import { createProductService } from "../services/create-product.service";
+
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
   return response.success({
     message: request.t("products.created"),

package/skills/use-repository/SKILL.md

@@ -276,10 +276,10 @@ export async function listFaqsService(filters: FaqListOptions) {
 ```
 
 ```ts title="src/app/faqs/controllers/list-faqs.controller.ts"
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { listFaqsService } from "../services/list-faqs.service";
 
-export const listFaqsController: RequestHandler = async (request, response: Response) => {
+export const listFaqsController: GuardedRequestHandler = async ({ request, response }) => {
   const { data, pagination } = await listFaqsService({
     ...request.all(),
     organization_id: request.user.organizationId,

package/skills/use-request-locals/SKILL.md

@@ -30,7 +30,7 @@ public locals: RequestLocals = {};
 ```ts title="src/app/observability/middleware/request-timing.middleware.ts"
 import type { Middleware } from "@warlock.js/core";
 
-export const requestTimingMiddleware: Middleware = request => {
+export const requestTimingMiddleware: Middleware = (request) => {
   request.startedAt = Date.now();
 };
 ```
@@ -38,7 +38,7 @@ export const requestTimingMiddleware: Middleware = request => {
 ```ts title="src/app/observability/controllers/timing.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const timingController: RequestHandler = async (request, response) => {
+export const timingController: RequestHandler = async ({ request, response }) => {
   return response.success({ elapsedMs: Date.now() - request.startedAt });
 };
 ```
@@ -123,7 +123,7 @@ Feature-local files such as `src/app/organizations/request-locals.d.ts` are equa
 
 Two rules the scaffold's own comments spell out, and both bite silently:
 
-- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an *ambient* module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
+- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an _ambient_ module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
 - **Keep them `interface`, not `type`.** This project otherwise prefers `type`; these are the named exception, because declaration merging is interface-only. `type RequestUser = { ... }` is a duplicate-identifier error, not an augmentation.
 
 On a project scaffolded before 5.1 there is no `src/typings.d.ts`, and `tsconfig.json` carries `"typeRoots": ["./src/typings.d.ts"]` — wrong twice, since `typeRoots` takes directories of `@types` packages rather than files, and that file did not exist. Drop the `typeRoots` entry, create the file, and list it under `include`.

package/skills/validate-input/SKILL.md

@@ -26,10 +26,10 @@ import type { Request, RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });

package/skills/warlock-conventions/SKILL.md

@@ -38,11 +38,11 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    ```
 
    ```ts title="src/app/<module>/controllers/create-<thing>.controller.ts"
-   import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+   import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
    import { type CreateThingSchema, createThingSchema } from "../schema/create-thing.schema";
    import { createThingService } from "../services/create-thing.service";
 
-   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async (request, response) => {
+   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({ request, response }) => {
      const thing = await createThingService(request.validated());
      return response.success({ thing });
    };

package/skills/wire-socket/SKILL.md

@@ -123,10 +123,10 @@ export async function notifyUserService(user: User, payload: unknown) {
 Then from a controller:
 
 ```ts
-import type { GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import type { GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { notifyUserService } from "../services/notify-user.service";
 
-export const sendNotificationController: GuardedRequestHandler = async (request, response) => {
+export const sendNotificationController: GuardedRequestHandler = async ({ request, response }) => {
   await notifyUserService(request.user, request.input("payload"));
   return response.success({ delivered: true });
 };

package/skills/write-middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-middleware
-description: 'Author HTTP middleware for @warlock.js/core — the `(request, response)` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.'
+description: 'Author HTTP middleware for @warlock.js/core — the `({ request, response })` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.'
 ---
 
 # Warlock — write a middleware
@@ -12,7 +12,7 @@ Middleware is a plain function that runs before the controller. Two outcomes: re
 ```ts title="src/app/<module>/utils/<name>.middleware.ts"
 import type { Middleware } from "@warlock.js/core";
 
-export const requireApiKey: Middleware = (request, response) => {
+export const requireApiKey: Middleware = ({ request, response }) => {
   const key = request.header("X-API-Key");
 
   if (!key || key !== process.env.API_KEY) {
@@ -23,16 +23,14 @@ export const requireApiKey: Middleware = (request, response) => {
 };
 ```
 
-That's the contract: `(request: Request, response: Response) => Response | undefined | void`. Async is fine — return a `Promise<Response | undefined | void>`.
+That's the contract: `(context: HttpContext<Request>) => Response | undefined | void`, where `context` is `{ request, response }`. Async is fine — return a `Promise<Response | undefined | void>`.
 
 The real type, from `@warlock.js/core/src/router/types.ts`:
 
 ```ts
 export type Middleware<MiddlewareRequest extends Request = Request> = {
-  (request: MiddlewareRequest, response: Response): MiddlewareResponse;
+  (context: HttpContext<MiddlewareRequest>): MiddlewareResponse;
 };
-
-export type MiddlewareResponse = ReturnedResponse | undefined | void;
 ```
 
 ## Short-circuit vs continue
@@ -42,7 +40,7 @@ The pattern is "return a response to stop, return nothing to continue":
 ```ts
 import type { Middleware } from "@warlock.js/core";
 
-export const requireFeatureFlag: Middleware = async (request, response) => {
+export const requireFeatureFlag: Middleware = async ({ request, response }) => {
   const flag = await loadFeatureFlag(request.input("organization_id"));
 
   if (!flag.enabled) {
@@ -60,8 +58,8 @@ If you short-circuit, the controller never runs. The response helper you pick (`
 You can attach arbitrary fields to `request` from a middleware, and they survive into the controller. The cleanest pattern is to extend `Request` via module augmentation in a `.d.ts` and assign in the middleware:
 
 ```ts title="src/app/feature-flags/middleware/load-feature-flag.middleware.ts"
-import type { Middleware } from "@warlock.js/core";
-import type { FeatureFlag } from "../models/feature-flag";
+import type { Middleware, Request, RequestUser } from "@warlock.js/core";
+import { FeatureFlag } from "../models/feature-flag";
 
 declare module "@warlock.js/core" {
   interface Request {
@@ -69,7 +67,7 @@ declare module "@warlock.js/core" {
   }
 }
 
-export const loadFeatureFlag: Middleware = async (request) => {
+export const loadFeatureFlag: Middleware<Request & { user: RequestUser }> = async ({ request }) => {
   request.featureFlag = await FeatureFlag.findBy("organization_id", request.user.organizationId);
 };
 ```
@@ -139,7 +137,7 @@ export function guarded(callback: () => void) {
 }
 
 export function guardedAdmin(callback: () => void) {
-  router.group({ prefix: "/admin", middleware: [authMiddleware()] }, callback);
+  router.group({ prefix: "/admin", middleware: [authMiddleware("admin")] }, callback);
 }
 
 export function publicRoutes(callback: () => void) {
@@ -157,7 +155,7 @@ guarded(() => {
 });
 ```
 
-`authMiddleware(allowedUserType?)` accepts a user-type string or array. Without an arg it just verifies the token is present; with `"user"` / `"admin"` it also checks the decoded `userType` matches.
+`authMiddleware(allowedUserType, tokenFrom?)` requires a user-type string or array — `[]` accepts any authenticated user without checking `userType`; `"user"` / `"admin"` also checks the decoded `userType` matches.
 
 ## Common patterns
 
@@ -184,13 +182,13 @@ router.group(
 ```ts
 import type { Middleware } from "@warlock.js/core";
 
-export const optionalAuth: Middleware = async (request, response) => {
+export const optionalAuth: Middleware = async ({ request, response }) => {
   if (!request.authorizationValue) {
     return; // anonymous — let it through
   }
 
   // token present → enforce it
-  return authMiddleware("user")(request, response);
+  return authMiddleware("user")({ request, response });
 };
 ```
 
@@ -206,7 +204,7 @@ export const optionalAuth: Middleware = async (request, response) => {
 - **Group middleware runs before per-route middleware**, in array order. The full chain is `app.all → group → per-route → controller`. Mind the order if you stack auth + rate-limit + audit.
 - **Middleware can be async.** Returning `Promise<undefined>` continues the chain. Returning `Promise<Response>` short-circuits. The framework awaits the result.
 - **Don't mutate `request.payload` directly.** Use `request.setValidatedData(...)` or attach a new named field (`request.featureFlag = ...`). The internals expect `payload.all` shapes to come from the validator pipeline.
-- **`Middleware` is generic over the request type.** For middleware that assumes a validated schema, narrow it: `const m: Middleware<CreateProductRequest> = (request) => { ... }`. But most middlewares run before validation, so the default `Middleware` is right.
+- **`Middleware` is generic over the request type.** For middleware that assumes a validated schema, narrow it: `const m: Middleware<CreateProductRequest> = ({ request }) => { ... }`. But most middlewares run before validation, so the default `Middleware` is right.
 - **No `next()` parameter.** Express-style `next()` doesn't apply here. The framework chains based on return value.
 - **`request.baseRequest` / `response.baseResponse` are escape hatches, not API.** They expose the underlying Fastify primitives for cases the framework hasn't covered yet (streaming was the historical precedent). Prefer framework helpers first — `response.send()`, `response.header()`, `response.replay()`, `request.input()`, `request.detectIp()`, etc. If you find yourself reaching for `baseResponse` or `baseRequest` for non-streaming work, that's a missing helper — file an issue. The cache and idempotency middlewares both shipped with a quietly-broken FastifyReply-return bug because they bypassed the helper layer; the framework now guards `Response.send()` against double-send, but the right answer is "use the helper."
 - **Behind any proxy, use `request.detectIp()` not `request.ip`.** `request.ip` is the immediate peer (likely your load balancer); `request.detectIp()` honors `X-Real-IP` / `X-Forwarded-For`. Either way, only trust the result as far as you trust the upstream chain — those headers are client-settable; verify the request came through your trusted edge before treating the value as authoritative.