cpeak 2.5.0 → 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)
 
@@ -267,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:
 
@@ -296,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",
@@ -304,6 +314,16 @@ 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:
@@ -366,12 +386,197 @@ 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();
 
@@ -386,6 +591,9 @@ server.beforeEach(render());
 // For parsing JSON bodies
 server.beforeEach(parseJSON());
 
+// For reading and setting cookies
+server.beforeEach(cookieParser({ secret: "your-secret-key" }));
+
 // Adding custom middleware functions
 server.beforeEach((req, res, next) => {
   req.custom = "This is some string";
@@ -437,6 +645,16 @@ server.route("get", "/api/document/:title", testRouteMiddleware, (req, res) => {
   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) => {
   // Make sure to specify a correct path and MIME type...

package/dist/index.d.ts

@@ -1,17 +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, ReqQueries = any> extends IncomingMessage {
     params: StringMap;
     query: ReqQueries;
     body?: ReqBody;
+    cookies?: StringMap;
+    signedCookies?: Record<string, string | false>;
     [key: string]: any;
 }
 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;
 }
@@ -30,14 +34,54 @@ 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 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 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;
@@ -48,34 +92,33 @@ declare enum ErrorCode {
     NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
     SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
     INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
-    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE"
+    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;
-    private _query?;
     get query(): StringMap;
 }
 declare class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
     sendFile(path: string, mime: string): Promise<void>;
     status(code: number): this;
-    redirect(location: string): 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 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 };