cpeak 2.4.3 → 2.6.0

package/README.md

@@ -34,6 +34,9 @@ This is an educational project that was started as part of the [Understanding No
     - [serveStatic](#servestatic)
     - [parseJSON](#parsejson)
     - [render](#render)
+    - [cookieParser](#cookieparser)
+    - [swagger](#swagger)
+    - [auth](#auth)
 - [Complete Example](#complete-example)
 - [Versioning Notice](#versioning-notice)
 
@@ -131,7 +134,7 @@ const requireAuth = (req, res, next, handleErr) => {
   return handleErr({ status: 401, message: "Unauthorized" });
 };
 
-server.route("get", "/profile", requireAuth, (req, res, handleErr) => {
+server.route("get", "/profile", requireAuth, (req, res) => {
   console.log(req.test); // this is a test value
 });
 ```
@@ -145,7 +148,7 @@ server.route(
   requireAuth,
   anotherFunction,
   oneMore,
-  (req, res, handleErr) => {
+  (req, res) => {
     // your logic
   }
 );
@@ -165,16 +168,15 @@ First add the HTTP method name you want to handle, then the path, and finally, t
 
 ### URL Variables & Parameters
 
-Since in HTTP these are called URL parameters: `/path?key1=value1&key2=value2&foo=900`, in Cpeak, we also call them `params` (short for HTTP URL parameters).
-We can also do custom path management, and we call them `vars` (short for URL variables).
+To be more consistent with the broader Node.js community and frameworks, we call the HTTP URL parameters (query strings) '**query**', and the path variables (route parameters) '**params**'.
 
 Here’s how we can read both:
 
 ```javascript
 // Imagine request URL is example.com/test/my-title/more-text?filter=newest
 server.route("patch", "/test/:title/more-text", (req, res) => {
-  const title = req.vars.title;
-  const filter = req.params.filter;
+  const title = req.params.title;
+  const filter = req.query.filter;
 
   console.log(title); // my-title
   console.log(filter); // newest
@@ -206,11 +208,23 @@ res.redirect("https://whatever.com");
 
 ### Error Handling
 
-If anywhere in your route functions or route middleware functions you want to return an error, it's cleaner to pass it to the `handleErr` function like this:
+If anywhere in your route functions or route middleware functions you want to return an error, you can just throw the error and let the automatic error handler catch it:
+
+```javascript
+server.route("get", "/api/document/:title", (req, res) => {
+  const title = req.params.title;
+
+  if (title.length > 500) throw { status: 400, message: "Title too long." };
+
+  // The rest of your logic...
+});
+```
+
+You can also make use of the `handleErr` callback function like this:
 
 ```javascript
 server.route("get", "/api/document/:title", (req, res, handleErr) => {
-  const title = req.vars.title;
+  const title = req.params.title;
 
   if (title.length > 500)
     return handleErr({ status: 400, message: "Title too long." });
@@ -219,7 +233,7 @@ server.route("get", "/api/document/:title", (req, res, handleErr) => {
 });
 ```
 
-And then handle all the errors like this in the `handleErr` callback:
+**Make sure** to call the `server.handleErr` and pass a function like this to have the automatic error handler work properly:
 
 ```javascript
 server.handleErr((error, req, res) => {
@@ -229,13 +243,13 @@ server.handleErr((error, req, res) => {
     // Log the unexpected errors somewhere so you can keep track of them...
     console.error(error);
     res.status(500).json({
-      error: "Sorry, something unexpected happened on our side.",
+      error: "Sorry, something unexpected happened on our side."
     });
   }
 });
 ```
 
-The error object is the object that you passed to the `handleErr` function earlier in your routes.
+_The error object is the object that you threw or passed to the `handleErr` function earlier in your routes._
 
 ### Listening
 
@@ -256,6 +270,9 @@ The list of utility functions as of now:
 - serveStatic
 - parseJSON
 - render
+- cookieParser
+- swagger
+- auth
 
 Including any one of them is done like this:
 
@@ -270,7 +287,7 @@ With this middleware function, you can automatically set a folder in your projec
 ```javascript
 server.beforeEach(
   serveStatic("./public", {
-    mp3: "audio/mpeg",
+    mp3: "audio/mpeg"
   })
 );
 ```
@@ -285,7 +302,11 @@ If you have file types in your public folder that are not one of the following,
   jpeg: "image/jpeg",
   png: "image/png",
   svg: "image/svg+xml",
+  gif: "image/gif",
+  ico: "image/x-icon",
   txt: "text/plain",
+  json: "application/json",
+  webmanifest: "application/manifest+json",
   eot: "application/vnd.ms-fontobject",
   otf: "font/otf",
   ttf: "font/ttf",
@@ -293,12 +314,24 @@ If you have file types in your public folder that are not one of the following,
   woff2: "font/woff2"
 ```
 
+You can also serve your static files under a URL prefix by passing a third argument with a `prefix` option. This is useful when you want all static assets to live under a specific path like `/static`:
+
+```javascript
+server.beforeEach(
+  serveStatic("./public", null, { prefix: "/static" })
+);
+```
+
+With this setup, a file at `./public/app.js` would be served at `/static/app.js` instead of `/app.js`. Pass `null` as the second argument if you don’t need any custom MIME types.
+
 #### parseJSON
 
 With this middleware function, you can easily read and send JSON in HTTP message bodies in route and middleware functions. Fire it up like this:
 
 ```javascript
-server.beforeEach(parseJSON);
+// You can pass an optional limit option to indicate the maximum
+// JSON body size that your server will accept.
+server.beforeEach(parseJSON({ limit: 1024 * 1024 })); // default value is 1024 * 1024 (1MB)
 ```
 
 Read and send JSON from HTTP messages like this:
@@ -333,7 +366,7 @@ server.route("get", "/", (req, res, next) => {
     "./public/index.html",
     {
       title: "Page title",
-      name: "Allan",
+      name: "Allan"
     },
     "text/html"
   );
@@ -353,25 +386,213 @@ You can then inject the variables into your file in {{ variable_name }} like thi
 </html>
 ```
 
+#### cookieParser
+
+With this middleware function, you can easily read and set cookies in your route and middleware functions. Fire it up like this:
+
+```javascript
+server.beforeEach(cookieParser());
+```
+
+If you need to use signed cookies, pass a secret:
+
+```javascript
+server.beforeEach(cookieParser({ secret: "your-secret-key" }));
+```
+
+Signed cookies use HMAC to verify integrity. The original value stays readable by the client, but any tampering with it will be detected on the server side. This makes them a solid choice for session identifiers or user IDs where you want to prevent impersonation without hiding the value itself.
+
+Read incoming cookies like this:
+
+```javascript
+server.route("get", "/dashboard", (req, res) => {
+  // Regular cookies
+  const theme = req.cookies.theme;
+
+  // Signed cookies — returns false if the signature is invalid or the value was tampered with
+  const userId = req.signedCookies.userId;
+
+  res.status(200).json({ theme, userId });
+});
+```
+
+Set cookies on the response like this:
+
+```javascript
+server.route("post", "/login", (req, res) => {
+  // A plain cookie
+  res.cookie("theme", "dark", { httpOnly: true, maxAge: 7 * 24 * 60 * 60 * 1000 });
+
+  // A signed cookie
+  res.cookie("userId", "abc123", { signed: true, httpOnly: true, secure: true });
+
+  res.status(200).json({ message: "Logged in" });
+});
+```
+
+Clear a cookie like this:
+
+```javascript
+res.clearCookie("userId");
+```
+
+The full list of cookie options you can pass as the third argument to `res.cookie()`:
+
+- `signed` — sign the cookie value with HMAC using the secret you provided to `cookieParser`
+- `httpOnly` — prevents client-side JavaScript from accessing the cookie
+- `secure` — instructs the browser to send the cookie only over HTTPS
+- `sameSite` — controls cross-site cookie behavior; accepts `"strict"`, `"lax"`, or `"none"`
+- `maxAge` — cookie lifetime in milliseconds
+- `expires` — a specific expiration `Date` for the cookie
+- `path` — path the cookie is valid for (defaults to `"/"`)
+- `domain` — domain the cookie is valid for
+
+#### swagger
+
+With this middleware function, you can serve an interactive Swagger UI for your API documentation. It works alongside the `serveStatic` utility and two npm packages: `swagger-ui-dist` (the Swagger UI static assets) and `yamljs` (to load your YAML spec file).
+
+Start by installing the dependencies:
+
+```bash
+npm install swagger-ui-dist yamljs
+```
+
+Then fire it up like this:
+
+```javascript
+import cpeak, { swagger, serveStatic } from "cpeak";
+import YAML from "yamljs";
+import swaggerUiDist from "swagger-ui-dist";
+import path from "node:path";
+
+const server = cpeak();
+
+const swaggerDocument = YAML.load(
+  path.join(path.resolve(), "./src/swagger.yml")
+);
+
+server.beforeEach(swagger(swaggerDocument));
+server.beforeEach(
+  serveStatic(swaggerUiDist.getAbsoluteFSPath(), undefined, {
+    prefix: "/api-docs",
+  })
+);
+```
+
+Once set up, your Swagger UI will be available at `/api-docs`. The `swagger` middleware handles serving your spec at `/api-docs/spec.json` and wiring up the Swagger UI initializer, while `serveStatic` serves all the Swagger UI static assets under the same prefix.
+
+If you want to serve the docs under a different path, pass it as the second argument to `swagger` and match the prefix in `serveStatic`:
+
+```javascript
+server.beforeEach(swagger(swaggerDocument, "/docs"));
+server.beforeEach(
+  serveStatic(swaggerUiDist.getAbsoluteFSPath(), undefined, {
+    prefix: "/docs",
+  })
+);
+```
+
+#### auth
+
+With this middleware you can add a full-fledged authentication system to your application with emails, username and password authentication, with features such as Forgot Password, Update Password and so forth. We have no external dependencies, with timing-safe comparisons throughout. It attaches helper methods directly to `req` so your route handlers stay clean.
+
+Fire it up like this:
+
+```javascript
+import cpeak, { parseJSON, cookieParser, auth } from "cpeak";
+
+const app = cpeak();
+
+app.beforeEach(parseJSON());
+app.beforeEach(cookieParser());
+
+app.beforeEach(
+  auth({
+    // Required
+    secret: "your-secret-min-32-chars-long!!!", // used to sign token IDs with HMAC
+    saveToken: async (tokenId, userId, expiresAt) => { /* store in your DB */ },
+    findToken: async (tokenId) => { /* return { userId, expiresAt } or null */ },
+
+    // Enables req.logout()
+    revokeToken: async (tokenId) => { /* delete from your DB */ },
+
+    // Optional PBKDF2 tuning (defaults shown):
+    iterations: 210_000,  // higher = slower brute-force
+    keylen: 64,           // derived key length in bytes
+    digest: "sha512",
+    saltSize: 32,
+
+    // Optional token signing tuning (defaults shown):
+    hmacAlgorithm: "sha256",
+    tokenIdSize: 20,
+    tokenExpiry: 7 * 24 * 60 * 60 * 1000, // 7 days in ms
+  })
+);
+```
+
+Once set up, the following methods are available on `req` inside your routes and middleware:
+
+| Method | Description |
+|--------|-------------|
+| `req.hashPassword({ password })` | Hashes a password with PBKDF2. Store the result; never store plaintext. |
+| `req.login({ password, hashedPassword, userId })` | Verifies the password and if correct, creates a signed token. Returns the token string to send to the client, or `null` on wrong password. |
+| `req.verifyToken(token)` | Validates a token's HMAC signature and expiry. Returns `{ userId }` or `null`. |
+| `req.logout(token)` | Revokes the token via your `revokeToken` callback. Only available when `revokeToken` is provided. |
+
+Here are the two most common middleware patterns you'll want to set up:
+
+```javascript
+// Throws 401 if the request has no valid token. Use on protected routes.
+const requireAuth = async (req, res, next) => {
+  const token = req.headers["authorization"];
+  if (!token) throw { status: 401, message: "Unauthorized." };
+
+  const result = await req.verifyToken(token);
+  if (!result) throw { status: 401, message: "Unauthorized." };
+
+  req.user = { id: result.userId };
+  next();
+};
+
+// Silently sets req.user when a valid token is present, but lets the request through either way.
+// Useful for routes accessible by both authenticated and unauthenticated users.
+const optionalAuth = async (req, _res, next) => {
+  const token = req.headers["authorization"];
+  if (token) {
+    const result = await req.verifyToken(token);
+    if (result) req.user = { id: result.userId };
+  }
+  next();
+};
+```
+
+For complete working examples, see:
+
+- [`examples/auth-localstorage.js`](examples/auth-localstorage.js) — token sent via the `Authorization` header (suited for SPAs and mobile clients)
+- [`examples/auth-cookies.js`](examples/auth-cookies.js) — token stored in an `httpOnly` cookie (protects against XSS)
+
 ## Complete Example
 
-Here you can see all the features that Cpeak offers, in one small piece of code:
+Here you can see all the features that Cpeak offers (excluding the authentication features), in one small piece of code:
 
 ```javascript
-import cpeak, { serveStatic, parseJSON, render } from "cpeak";
+import cpeak, { serveStatic, parseJSON, render, cookieParser } from "cpeak";
 
 const server = cpeak();
 
 server.beforeEach(
   serveStatic("./public", {
-    mp3: "audio/mpeg",
+    mp3: "audio/mpeg"
   })
 );
 
 server.beforeEach(render());
 
 // For parsing JSON bodies
-server.beforeEach(parseJSON);
+server.beforeEach(parseJSON());
+
+// For reading and setting cookies
+server.beforeEach(cookieParser({ secret: "your-secret-key" }));
 
 // Adding custom middleware functions
 server.beforeEach((req, res, next) => {
@@ -383,7 +604,7 @@ server.beforeEach((req, res, next) => {
 const testRouteMiddleware = (req, res, next, handleErr) => {
   req.whatever = "some calculated value maybe";
 
-  if (req.vars.test !== "something special") {
+  if (req.params.test !== "something special") {
     return handleErr({ status: 400, message: "an error message" });
   }
 
@@ -396,7 +617,7 @@ server.route("get", "/", (req, res, next) => {
     "<path-to-file-relative-to-cwd>",
     {
       test: "some testing value",
-      number: "2343242",
+      number: "2343242"
     },
     "<mime-type>"
   );
@@ -406,28 +627,33 @@ server.route("get", "/old-url", testRouteMiddleware, (req, res, next) => {
   return res.redirect("/new-url");
 });
 
-server.route(
-  "get",
-  "/api/document/:title",
-  testRouteMiddleware,
-  (req, res, handleErr) => {
-    // Reading URL variables
-    const title = req.vars.title;
+server.route("get", "/api/document/:title", testRouteMiddleware, (req, res) => {
+  // Reading URL variables (route parameters)
+  const title = req.params.title;
 
-    // Reading URL parameters (like /users?filter=active)
-    const filter = req.params.filter;
+  // Reading URL parameters (query strings) (like /users?filter=active)
+  const filter = req.query.filter;
 
-    // Reading JSON request body
-    const anything = req.body.anything;
+  // Reading JSON request body
+  const anything = req.body.anything;
 
-    // Handling errors
-    if (anything === "not-expected-thing")
-      return handleErr({ status: 400, message: "Invalid property." });
+  // Handling errors
+  if (anything === "not-expected-thing")
+    throw { status: 400, message: "Invalid property." };
 
-    // Sending a JSON response
-    res.status(200).json({ message: "This is a test response" });
-  }
-);
+  // Sending a JSON response
+  res.status(200).json({ message: "This is a test response" });
+});
+
+// Reading and setting cookies
+server.route("post", "/login", (req, res) => {
+  // Reads are available via req.cookies and req.signedCookies
+  const sessionId = req.signedCookies.sessionId;
+
+  // Set a signed session cookie
+  res.cookie("sessionId", "abc123", { signed: true, httpOnly: true, secure: true });
+  res.status(200).json({ message: "Logged in" });
+});
 
 // Sending a file response
 server.route("get", "/file", (req, res) => {
@@ -442,7 +668,7 @@ server.handleErr((error, req, res) => {
   } else {
     console.error(error);
     res.status(500).json({
-      error: "Sorry, something unexpected happened from our side.",
+      error: "Sorry, something unexpected happened from our side."
     });
   }
 });

package/dist/index.d.ts

@@ -1,18 +1,21 @@
+import * as net from 'net';
 import http, { IncomingMessage, ServerResponse } from 'node:http';
 
-type Cpeak$1 = ReturnType<typeof cpeak>;
 type StringMap = Record<string, string>;
-interface CpeakRequest<ReqBody = any, ReqParams = any> extends IncomingMessage {
-    params: ReqParams;
-    vars?: StringMap;
+interface CpeakRequest<ReqBody = any, ReqQueries = any> extends IncomingMessage {
+    params: StringMap;
+    query: ReqQueries;
     body?: ReqBody;
+    cookies?: StringMap;
+    signedCookies?: Record<string, string | false>;
     [key: string]: any;
-    query: ReqParams;
 }
 interface CpeakResponse extends ServerResponse {
     sendFile: (path: string, mime: string) => Promise<void>;
     status: (code: number) => CpeakResponse;
-    redirect: (location: string) => CpeakResponse;
+    attachment: (filename?: string) => CpeakResponse;
+    cookie: (name: string, value: string, options?: any) => CpeakResponse;
+    redirect: (location: string) => void;
     json: (data: any) => void;
     [key: string]: any;
 }
@@ -31,35 +34,91 @@ interface RoutesMap {
     [method: string]: Route[];
 }
 
-declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
+declare const parseJSON: (options?: {
+    limit?: number;
+}) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
-declare const parseJSON: (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
+declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap, options?: {
+    prefix?: string;
+}) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
 
 declare const render: () => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
-declare function frameworkError(message: string, skipFn: Function, code?: string): Error & {
+declare const swagger: (spec: object, prefix?: string) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
+
+interface PbkdfOptions {
+    iterations?: number;
+    keylen?: number;
+    digest?: string;
+    saltSize?: number;
+}
+interface AuthOptions extends PbkdfOptions {
+    secret: string;
+    saveToken: (tokenId: string, userId: string, expiresAt: Date) => Promise<void>;
+    findToken: (tokenId: string) => Promise<{
+        userId: string;
+        expiresAt: Date;
+    } | null>;
+    tokenExpiry?: number;
+    hmacAlgorithm?: string;
+    tokenIdSize?: number;
+    revokeToken?: (tokenId: string) => Promise<void>;
+}
+declare function hashPassword(password: string, options?: PbkdfOptions): Promise<string>;
+declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+declare function auth(options: AuthOptions): Middleware;
+
+interface CookieOptions {
+    signed?: boolean;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+}
+declare function cookieParser(options?: {
+    secret?: string;
+}): (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
+
+declare function frameworkError(message: string, skipFn: Function, code?: string, status?: number): Error & {
     code?: string;
+    cpeak_err?: boolean;
 };
 declare enum ErrorCode {
     MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
     FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
     NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
-    SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL"
+    SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
+    INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
+    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+    WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET"
+}
+declare class CpeakIncomingMessage extends http.IncomingMessage {
+    #private;
+    body: any;
+    params: StringMap;
+    get query(): StringMap;
+}
+declare class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+    sendFile(path: string, mime: string): Promise<void>;
+    status(code: number): this;
+    attachment(filename?: string): this;
+    redirect(location: string): void;
+    json(data: any): void;
 }
 declare class Cpeak {
     #private;
-    private server;
-    private routes;
-    private middleware;
-    private _handleErr?;
     constructor();
     route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]): void;
     beforeEach(cb: Middleware): void;
     handleErr(cb: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void): void;
-    listen(port: number, cb?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    listen(port: number, cb?: () => void): http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
+    address(): string | net.AddressInfo | null;
     close(cb?: (err?: Error) => void): void;
 }
 
 declare function cpeak(): Cpeak;
 
-export { type Cpeak$1 as Cpeak, type CpeakRequest, type CpeakResponse, ErrorCode, type HandleErr, type Handler, type Middleware, type Next, type RouteMiddleware, type RoutesMap, cpeak as default, frameworkError, parseJSON, render, serveStatic };
+export { type AuthOptions, type CookieOptions, Cpeak, CpeakIncomingMessage, type CpeakRequest, type CpeakResponse, CpeakServerResponse, ErrorCode, type HandleErr, type Handler, type Middleware, type Next, type PbkdfOptions, type RouteMiddleware, type RoutesMap, auth, cookieParser, cpeak as default, frameworkError, hashPassword, parseJSON, render, serveStatic, swagger, verifyPassword };