feat: Cookies

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Version 28
 
+### v28.1.0
+
+- Added support for cookie handling:
+  - Cookie parsing can be enabled and configured in config (requires to install `cookie-parser`);
+  - `cookies` and `signedCookies` can be used as `inputSources` in config;
+  - `createCookieMiddleware()` creates a Middleware that exposes `setCookie()` and `clearCookie()` helpers into context
+    as well as the `getCookie()` one as an alternative to using cookies within `inputSources`;
+  - Documentation depicts request parameters when Middleware has `security` schema with `type: cookie`.
+
 ### v28.0.1
 
 - Adjusted the list of well-known headers, recognized by Documentation generator:

README.md

@@ -34,17 +34,18 @@ Start your API server with I/O schema validation and custom middlewares in minut
    15. [Child logger](#child-logger)
 5. [Advanced features](#advanced-features)
    1. [Customizing input sources](#customizing-input-sources)
-   2. [Headers as input source](#headers-as-an-input-source)
-   3. [Response customization](#response-customization)
-   4. [Empty response](#empty-response)
-   5. [Non-JSON response](#non-json-response) including file downloads
-   6. [Error handling](#error-handling)
-   7. [Production mode](#production-mode)
-   8. [HTML Forms (URL encoded)](#html-forms-url-encoded)
-   9. [File uploads](#file-uploads)
-   10. [Connect to your own express app](#connect-to-your-own-express-app)
-   11. [Testing endpoints](#testing-endpoints)
-   12. [Testing middlewares](#testing-middlewares)
+   2. [Headers as an input source](#headers-as-an-input-source)
+   3. [Cookies](#cookies)
+   4. [Response customization](#response-customization)
+   5. [Empty response](#empty-response)
+   6. [Non-JSON response](#non-json-response) including file downloads
+   7. [Error handling](#error-handling)
+   8. [Production mode](#production-mode)
+   9. [HTML Forms (URL encoded)](#html-forms-url-encoded)
+   10. [File uploads](#file-uploads)
+   11. [Connect to your own express app](#connect-to-your-own-express-app)
+   12. [Testing endpoints](#testing-endpoints)
+   13. [Testing middlewares](#testing-middlewares)
 6. [Integration and Documentation](#integration-and-documentation)
    1. [Zod Plugin](#zod-plugin)
    2. [End-to-End Type Safety](#end-to-end-type-safety)
@@ -818,6 +819,49 @@ factory.build({
 });
 ```
 
+## Cookies
+
+Install `cookie-parser` as well as `@types/cookie-parser` and enable `cookies` in your config. To validate cookies add
+`"cookies"` and/or `"signedCookies"` to your `inputSources` (the order [matters](#customizing-input-sources)!):
+
+```ts
+import { createConfig } from "express-zod-api";
+
+const config = createConfig({
+  cookies: { secret: "my-secret" }, // or true; the secret enables signedCookies
+  inputSources: {
+    get: ["query", "params", "cookies", "signedCookies"], // for methods of your choice
+  },
+});
+```
+
+Consider `createCookieMiddleware()` that makes a Middleware providing `setCookie()` and `clearCookie()` helpers,
+as well as `getCookie()` — alternative to the cookies as an input source:
+
+```ts
+import { createCookieMiddleware, Middleware } from "express-zod-api";
+
+const cookieDrivenFactory = factory
+  .addMiddleware(
+    createCookieMiddleware({ httpOnly: true, sameSite: "lax", path: "/" }), // recommended base options
+  )
+  .addMiddleware(
+    new Middleware({
+      security: { type: "cookie", name: "session" }, // improves Documentation
+      input: z.object({ session: z.string() }), // alternatively, use getCookie
+      handler: async ({ input: { session }, ctx: { getCookie } }) => {
+        assert.equal(session, getCookie("session")); // getCookie reads from signedCookies first
+      },
+    }),
+  );
+
+const sessionSettingEndpoint = cookieDrivenFactory.buildVoid({
+  handler: async ({ ctx: { getCookie, setCookie } }) => {
+    setCookie("session", "abc123", { httpOnly: false }); // overridden cookie options
+  },
+});
+```
+
 ## Response customization
 
 `ResultHandler` is responsible for transmitting consistent responses containing the endpoint output or an error.

example/config.ts

@@ -13,6 +13,7 @@ export const config = createConfig({
     limitError: createHttpError(413, "The file is too large"), // affects uploadAvatarEndpoint
   },
   compression: true, // affects sendAvatarEndpoint
+  cookies: true, // for uploadAvatarEndpoint
   // third-party middlewares serving their own routes or establishing their own routing besides the API
   beforeRouting: ({ app }) => {
     app.use(
@@ -23,6 +24,7 @@ export const config = createConfig({
   },
   inputSources: {
     patch: ["headers", "body", "params"], // affects authMiddleware used by updateUserEndpoint
+    post: ["body", "params", "files", "cookies"], // cookies for uploadAvatarEndpoint
   },
   cors: true,
 });
@@ -47,5 +49,6 @@ declare module "express-zod-api" {
     files: unknown;
     subscriptions: unknown;
     forms: unknown;
+    cookies: unknown;
   }
 }

example/endpoints/login.ts

@@ -0,0 +1,31 @@
+import { cookieAssistedFactory } from "../factories.ts";
+import { z } from "zod";
+import { randomUUID, scrypt } from "node:crypto";
+import createHttpError from "http-errors";
+import assert from "node:assert/strict";
+import { promisify } from "node:util";
+
+/** @desc The endpoint demonstrates setting a cookie */
+export const loginEndpoint = cookieAssistedFactory.build({
+  method: "post",
+  tag: "cookies",
+  input: z.object({
+    username: z.string().trim().nonempty(),
+    password: z.string().trim().nonempty(),
+  }),
+  output: z.object({ message: z.string() }),
+  handler: async ({ input: { username, password }, ctx: { setCookie } }) => {
+    const key = await promisify<string, string, number, Buffer>(scrypt)(
+      password,
+      "kinda salt",
+      16,
+    );
+    assert(
+      username === "admin" &&
+        key.toString("hex") === "79ad19b8c03bc92a2f25ed865400264e",
+      createHttpError(401, "Invalid credentials"),
+    );
+    setCookie("session", { token: randomUUID() });
+    return { message: "Logged in" };
+  },
+});

example/endpoints/upload-avatar.ts

@@ -1,8 +1,12 @@
 import { z } from "zod";
-import { defaultEndpointsFactory, ez } from "express-zod-api";
+import { ez } from "express-zod-api";
 import { createHash } from "node:crypto";
+import { cookieAuthenticatedFactory } from "../factories.ts";
+import assert from "node:assert/strict";
+import createHttpError from "http-errors";
 
-export const uploadAvatarEndpoint = defaultEndpointsFactory.build({
+/** @desc The endpoint demonstrates handling a file upload and cookie as an input source */
+export const uploadAvatarEndpoint = cookieAuthenticatedFactory.build({
   method: "post",
   tag: "files",
   description: "Handles a file upload.",
@@ -16,11 +20,14 @@ export const uploadAvatarEndpoint = defaultEndpointsFactory.build({
     hash: z.string(),
     otherInputs: z.record(z.string(), z.any()),
   }),
-  handler: async ({ input: { avatar, ...rest } }) => ({
-    name: avatar.name,
-    size: avatar.size,
-    mime: avatar.mimetype,
-    hash: createHash("sha1").update(avatar.data).digest("hex"),
-    otherInputs: rest,
-  }),
+  handler: async ({ input: { avatar, ...rest }, ctx: { session } }) => {
+    assert(session.token, createHttpError(401, "Unauthorized"));
+    return {
+      name: avatar.name,
+      size: avatar.size,
+      mime: avatar.mimetype,
+      hash: createHash("sha1").update(avatar.data).digest("hex"),
+      otherInputs: rest,
+    };
+  },
 });

example/example.client.ts

@@ -205,6 +205,38 @@ interface HeadV1UserListNegativeResponseVariants {
   400: HeadV1UserListNegativeVariant1;
 }
 
+/** post /v1/login */
+type PostV1LoginInput = {
+  username: string;
+  password: string;
+};
+
+/** post /v1/login */
+type PostV1LoginPositiveVariant1 = {
+  status: "success";
+  data: {
+    message: string;
+  };
+};
+
+/** post /v1/login */
+interface PostV1LoginPositiveResponseVariants {
+  200: PostV1LoginPositiveVariant1;
+}
+
+/** post /v1/login */
+type PostV1LoginNegativeVariant1 = {
+  status: "error";
+  error: {
+    message: string;
+  };
+};
+
+/** post /v1/login */
+interface PostV1LoginNegativeResponseVariants {
+  400: PostV1LoginNegativeVariant1;
+}
+
 /** get /v1/avatar/send */
 type GetV1AvatarSendInput = {
   userId: string;
@@ -291,6 +323,9 @@ interface HeadV1AvatarStreamNegativeResponseVariants {
 
 /** post /v1/avatar/upload */
 type PostV1AvatarUploadInput = {
+  session: {
+    token: string;
+  };
   avatar: any;
 };
 
@@ -513,6 +548,7 @@ export type Path =
   | "/v1/user/:id"
   | "/v1/user/create"
   | "/v1/user/list"
+  | "/v1/login"
   | "/v1/avatar/send"
   | "/v1/avatar/stream"
   | "/v1/avatar/upload"
@@ -531,6 +567,7 @@ export interface Input {
   "post /v1/user/create": PostV1UserCreateInput;
   "get /v1/user/list": GetV1UserListInput;
   "head /v1/user/list": HeadV1UserListInput;
+  "post /v1/login": PostV1LoginInput;
   /** @deprecated */
   "get /v1/avatar/send": GetV1AvatarSendInput;
   /** @deprecated */
@@ -554,6 +591,7 @@ export interface PositiveResponse {
   "post /v1/user/create": SomeOf<PostV1UserCreatePositiveResponseVariants>;
   "get /v1/user/list": SomeOf<GetV1UserListPositiveResponseVariants>;
   "head /v1/user/list": SomeOf<HeadV1UserListPositiveResponseVariants>;
+  "post /v1/login": SomeOf<PostV1LoginPositiveResponseVariants>;
   /** @deprecated */
   "get /v1/avatar/send": SomeOf<GetV1AvatarSendPositiveResponseVariants>;
   /** @deprecated */
@@ -577,6 +615,7 @@ export interface NegativeResponse {
   "post /v1/user/create": SomeOf<PostV1UserCreateNegativeResponseVariants>;
   "get /v1/user/list": SomeOf<GetV1UserListNegativeResponseVariants>;
   "head /v1/user/list": SomeOf<HeadV1UserListNegativeResponseVariants>;
+  "post /v1/login": SomeOf<PostV1LoginNegativeResponseVariants>;
   /** @deprecated */
   "get /v1/avatar/send": SomeOf<GetV1AvatarSendNegativeResponseVariants>;
   /** @deprecated */
@@ -607,6 +646,8 @@ export interface EncodedResponse {
     GetV1UserListNegativeResponseVariants;
   "head /v1/user/list": HeadV1UserListPositiveResponseVariants &
     HeadV1UserListNegativeResponseVariants;
+  "post /v1/login": PostV1LoginPositiveResponseVariants &
+    PostV1LoginNegativeResponseVariants;
   /** @deprecated */
   "get /v1/avatar/send": GetV1AvatarSendPositiveResponseVariants &
     GetV1AvatarSendNegativeResponseVariants;
@@ -655,6 +696,9 @@ export interface Response {
   "head /v1/user/list":
     | PositiveResponse["head /v1/user/list"]
     | NegativeResponse["head /v1/user/list"];
+  "post /v1/login":
+    | PositiveResponse["post /v1/login"]
+    | NegativeResponse["post /v1/login"];
   /** @deprecated */
   "get /v1/avatar/send":
     | PositiveResponse["get /v1/avatar/send"]
@@ -702,6 +746,7 @@ export const endpointTags = {
   "post /v1/user/create": ["users"],
   "get /v1/user/list": ["users"],
   "head /v1/user/list": ["users"],
+  "post /v1/login": ["cookies"],
   "get /v1/avatar/send": ["files", "users"],
   "head /v1/avatar/send": ["files", "users"],
   "get /v1/avatar/stream": ["users", "files"],