cpeak 2.4.3 → 2.6.0

package/lib/utils/auth.ts

@@ -0,0 +1,170 @@
+import { randomBytes, pbkdf2, createHmac, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+import type { Middleware } from "../types";
+import { frameworkError, ErrorCode } from "../index";
+
+const pbkdf2Async = promisify(pbkdf2);
+
+const DEFAULTS = {
+  iterations: 210_000,
+  keylen: 64,
+  digest: "sha512",
+  saltSize: 32,
+  hmacAlgorithm: "sha256",
+  tokenIdSize: 20,
+  tokenExpiry: 7 * 24 * 60 * 60 * 1000 // 7 days in ms
+} as const;
+
+export interface PbkdfOptions {
+  iterations?: number;
+  keylen?: number;
+  digest?: string;
+  saltSize?: number;
+}
+
+export 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>;
+}
+
+export async function hashPassword(
+  password: string,
+  options?: PbkdfOptions
+): Promise<string> {
+  const iterations = options?.iterations ?? DEFAULTS.iterations;
+  const keylen = options?.keylen ?? DEFAULTS.keylen;
+  const digest = options?.digest ?? DEFAULTS.digest;
+  const saltSize = options?.saltSize ?? DEFAULTS.saltSize;
+  const salt = randomBytes(saltSize);
+  const hash = await pbkdf2Async(password, salt, iterations, keylen, digest);
+  return `pbkdf2:${iterations}:${keylen}:${digest}:${salt.toString("hex")}:${hash.toString("hex")}`;
+}
+
+export async function verifyPassword(
+  password: string,
+  stored: string
+): Promise<boolean> {
+  // When argon2 is added, dispatch on the prefix here.
+  const withoutPrefix = stored.slice(stored.indexOf(":") + 1);
+  const parts = withoutPrefix.split(":");
+  if (parts.length !== 5) return false;
+  const [itersStr, keylenStr, digest, saltHex, hashHex] = parts;
+  const iterations = parseInt(itersStr, 10);
+  const keylen = parseInt(keylenStr, 10);
+  if (!digest || !saltHex || !hashHex || isNaN(iterations) || isNaN(keylen))
+    return false;
+  const salt = Buffer.from(saltHex, "hex");
+  const hash = await pbkdf2Async(password, salt, iterations, keylen, digest);
+  const storedHash = Buffer.from(hashHex, "hex");
+  if (storedHash.length !== hash.length) return false;
+  return timingSafeEqual(hash, storedHash);
+}
+
+function signToken(tokenId: string, secret: string, algorithm: string): string {
+  const sig = createHmac(algorithm, secret).update(tokenId).digest("hex");
+  return `${tokenId}.${sig}`;
+}
+
+function extractTokenId(
+  token: string,
+  secret: string,
+  algorithm: string
+): string | null {
+  const dot = token.indexOf(".");
+  if (dot === -1) return null;
+  const tokenId = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+  const expected = createHmac(algorithm, secret).update(tokenId).digest("hex");
+  const expectedBuf = Buffer.from(expected, "hex");
+  const actualBuf = Buffer.from(sig, "hex");
+  if (expectedBuf.length !== actualBuf.length) return null;
+  if (!timingSafeEqual(expectedBuf, actualBuf)) return null;
+  return tokenId;
+}
+
+export function auth(options: AuthOptions): Middleware {
+  if (!options.secret || options.secret.length < 32) {
+    throw frameworkError(
+      "Secret must be at least 32 characters. HMAC security is only as strong as the key.",
+      auth,
+      ErrorCode.WEAK_SECRET
+    );
+  }
+
+  const {
+    secret,
+    saveToken,
+    findToken,
+    revokeToken,
+    tokenExpiry = DEFAULTS.tokenExpiry,
+    hmacAlgorithm = DEFAULTS.hmacAlgorithm,
+    tokenIdSize = DEFAULTS.tokenIdSize
+  } = options;
+
+  const pbkdfOpts: PbkdfOptions = {
+    iterations: options.iterations,
+    keylen: options.keylen,
+    digest: options.digest,
+    saltSize: options.saltSize
+  };
+
+  const _hashPassword = ({ password }: { password: string }) =>
+    hashPassword(password, pbkdfOpts);
+
+  const login = async ({
+    password,
+    hashedPassword,
+    userId
+  }: {
+    password: string;
+    hashedPassword: string;
+    userId: string;
+  }): Promise<string | null> => {
+    const isMatch = await verifyPassword(password, hashedPassword);
+    if (!isMatch) return null;
+    const tokenId = randomBytes(tokenIdSize).toString("hex");
+    const token = signToken(tokenId, secret, hmacAlgorithm);
+    await saveToken(tokenId, userId, new Date(Date.now() + tokenExpiry));
+    return token;
+  };
+
+  const verifyToken = async (
+    token: string
+  ): Promise<{ userId: string } | null> => {
+    if (!token) return null;
+    const tokenId = extractTokenId(token, secret, hmacAlgorithm);
+    if (!tokenId) return null;
+    const record = await findToken(tokenId);
+    if (!record) return null;
+    if (new Date(record.expiresAt) < new Date()) return null;
+    return { userId: record.userId };
+  };
+
+  const logout = revokeToken
+    ? async (token: string): Promise<boolean> => {
+        const tokenId = extractTokenId(token, secret, hmacAlgorithm);
+        if (!tokenId) return false;
+        await revokeToken(tokenId);
+        return true;
+      }
+    : undefined;
+
+  return (req, _res, next) => {
+    req.hashPassword = _hashPassword;
+    req.login = login;
+    req.verifyToken = verifyToken;
+    if (logout) req.logout = logout;
+    next();
+  };
+}

package/lib/utils/cookieParser.ts

@@ -0,0 +1,189 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { CpeakRequest, CpeakResponse, Next } from "../types";
+import { frameworkError, ErrorCode } from "../index";
+
+export interface CookieOptions {
+  signed?: boolean;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none";
+  maxAge?: number; // ms
+  expires?: Date;
+  path?: string;
+  domain?: string;
+}
+
+// This will sign the cookie value with HMAC with the secret.
+// Ideal for data like user IDs or session IDs, where you want to ensure the integrity of the cookie value without encryption.
+// So this way, imagine you save a user ID in the cookie. By signing it, you can detect if the client has tampered with the cookie value
+// (e.g., changing the user ID to impersonate another user).
+// However, since it's not encrypted, the actual user ID is still visible  to the client.
+// This is a common approach for session cookies where you want to prevent tampering but don't mind if the value is visible.
+function sign(value: string, secret: string): string {
+  const sig = createHmac("sha256", secret).update(value).digest("base64url");
+  return `s:${value}.${sig}`;
+}
+
+function unsign(signed: string, secret: string): string | false {
+  if (!signed.startsWith("s:")) return false;
+  const withoutPrefix = signed.slice(2);
+  const lastDot = withoutPrefix.lastIndexOf(".");
+  if (lastDot === -1) return false;
+  const value = withoutPrefix.slice(0, lastDot);
+  const sig = withoutPrefix.slice(lastDot + 1);
+  const expected = createHmac("sha256", secret)
+    .update(value)
+    .digest("base64url");
+  const expectedBuf = Buffer.from(expected);
+  const actualBuf = Buffer.from(sig);
+  if (expectedBuf.length !== actualBuf.length) return false;
+  if (!timingSafeEqual(expectedBuf, actualBuf)) return false;
+  return value;
+}
+
+// Parses the raw value of an HTTP `Cookie` request header into a name->value
+// This should be compatible with the RFC 6265 HTTP specification
+function parseRawCookies(header: string): Record<string, string> {
+  // Use a null-prototype object to prevent prototype pollution attacks when assigning cookie names like "__proto__" or "constructor".
+  const cookies: Record<string, string> = Object.create(null);
+  if (!header) return cookies;
+
+  const pairs = header.split(";");
+
+  for (let i = 0; i < pairs.length; i++) {
+    const pair = pairs[i];
+    const equalSignIndex = pair.indexOf("=");
+
+    // RFC 6265: cookie-pair requires '='. Pairs without one (e.g. a
+    // bare flag like `Cookie: foo`) are not valid cookie-pairs and we skip them.
+    // Note we use the FIRST '=' only. So values like base64 padding (`token=YWJjPT0=`) must keep trailing '='s.
+    if (equalSignIndex === -1) continue;
+
+    const key = pair.slice(0, equalSignIndex).trim();
+    // Drop empty names and honour the FIRST occurrence on duplicates (Specs say servers SHOULD NOT rely on order.
+    // We pick first-wins for stability).
+    if (!key || cookies[key] !== undefined) continue;
+
+    let val = pair.slice(equalSignIndex + 1).trim();
+
+    // Cookie values are sometimes sent wrapped in double quotes (like name="hello world"), so we strip the outer "
+    // characters to get the actual value hello world.
+    // The val.length > 1 guard handles the edge case where the value is literally just a single " — without it, that one
+    // character would match both the "starts with quote" and "ends with quote" checks, and slice(1, -1) would wipe it out
+    // to an empty string.
+    if (val.length > 1 && val[0] === '"' && val[val.length - 1] === '"') {
+      val = val.slice(1, -1);
+    }
+
+    // Percent-decoding cookie values is a server-side convention (not part of
+    // RFC 6265 itself), but it's what Express and most ecosystem libraries do,
+    // so we follow suit for compatibility. Skip the decode entirely when there's no
+    // '%' to save work on the common case, and fall back to the raw value if
+    // decodeURIComponent throws on malformed input rather than crashing the
+    // whole request.
+    try {
+      cookies[key] = val.indexOf("%") !== -1 ? decodeURIComponent(val) : val;
+    } catch (e) {
+      cookies[key] = val;
+    }
+  }
+  return cookies;
+}
+
+// One example output: "session=abc123; Path=/dashboard; Domain=example.com; Max-Age=86400; Expires=Thu, 31 Dec 2026 00:00:00 GMT; HttpOnly; Secure; SameSite=Strict"
+function buildSetCookieHeader(
+  name: string,
+  value: string,
+  options: CookieOptions
+): string {
+  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];
+  const path = options.path ?? "/";
+  parts.push(`Path=${path}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.maxAge !== undefined)
+    parts.push(`Max-Age=${Math.floor(options.maxAge / 1000)}`);
+  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.secure) parts.push("Secure");
+  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+  return parts.join("; ");
+}
+
+// Without this helper, calling res.cookie("a", "1") then res.cookie("b", "2") would overwrite the first cookie instead
+// of sending both.
+function appendSetCookie(res: CpeakResponse, header: string) {
+  const existing = res.getHeader("Set-Cookie");
+  if (!existing) {
+    res.setHeader("Set-Cookie", [header]);
+  } else if (Array.isArray(existing)) {
+    res.setHeader("Set-Cookie", [...existing, header]);
+  } else {
+    res.setHeader("Set-Cookie", [String(existing), header]);
+  }
+}
+
+export function cookieParser(options: { secret?: string } = {}) {
+  const { secret } = options;
+
+  if (secret !== undefined && secret.length < 32) {
+    throw frameworkError(
+      "Secret must be at least 32 characters. HMAC security is only as strong as the key.",
+      cookieParser,
+      ErrorCode.WEAK_SECRET
+    );
+  }
+
+  return (req: CpeakRequest, res: CpeakResponse, next: Next) => {
+    const rawHeader = req.headers["cookie"] || "";
+    const raw = parseRawCookies(rawHeader);
+
+    // Mirror parseRawCookies and use null-prototype maps here too. If we used
+    // a regular `{}`, the assignment below would invoke Object.prototype's
+    // __proto__ setter (no-op for string values), silently dropping any
+    // cookie literally named __proto__ — undoing the fix in parseRawCookies.
+    const cookies: Record<string, string> = Object.create(null);
+    const signedCookies: Record<string, string | false> = Object.create(null);
+
+    for (const [key, val] of Object.entries(raw)) {
+      // The "s:" prefix is the marker we add in `sign()` for HMAC-signed
+      // cookies. Route those through unsign so the handler sees the original
+      // value (or `false` if the signature didn't verify).
+      if (val.startsWith("s:") && secret) {
+        signedCookies[key] = unsign(val, secret);
+      } else {
+        cookies[key] = val;
+      }
+    }
+
+    // The separation is intentional signal: "these were signed and verified, trust them more."
+    req.cookies = cookies;
+    req.signedCookies = signedCookies;
+
+    res.cookie = (name: string, value: string, options: CookieOptions = {}) => {
+      let finalValue = value;
+      if (options.signed) {
+        if (!secret)
+          throw new Error(
+            "cookieParser: secret is required to use signed cookies"
+          );
+        finalValue = sign(value, secret);
+      }
+      appendSetCookie(res, buildSetCookieHeader(name, finalValue, options));
+      return res;
+    };
+
+    res.clearCookie = (name: string, options: CookieOptions = {}) => {
+      appendSetCookie(
+        res,
+        buildSetCookieHeader(name, "", {
+          ...options,
+          maxAge: 0,
+          expires: new Date(0)
+        })
+      );
+      return res;
+    };
+
+    next();
+  };
+}

package/lib/utils/index.ts

@@ -1,5 +1,20 @@
 import { parseJSON } from "./parseJSON";
 import { serveStatic } from "./serveStatic";
 import { render } from "./render";
+import { swagger } from "./swagger";
+import { auth, hashPassword, verifyPassword } from "./auth";
+import type { AuthOptions, PbkdfOptions } from "./auth";
+import { cookieParser } from "./cookieParser";
+import type { CookieOptions } from "./cookieParser";
 
-export { serveStatic, parseJSON, render };
+export {
+  serveStatic,
+  parseJSON,
+  render,
+  swagger,
+  auth,
+  hashPassword,
+  verifyPassword,
+  cookieParser
+};
+export type { AuthOptions, PbkdfOptions, CookieOptions };

package/lib/utils/parseJSON.ts

@@ -1,30 +1,83 @@
 import type { CpeakRequest, CpeakResponse, Next } from "../types";
+import { Buffer } from "node:buffer";
+import { frameworkError, ErrorCode } from "../index";
+
+// Check if Content-Type is JSON
+function isJSON(contentType: string | undefined) {
+  if (!contentType) return false;
+  if (contentType === "application/json") return true;
+  return (
+    contentType.startsWith("application/json") || contentType.includes("+json")
+  );
+}
 
 // Parsing JSON
-const parseJSON = (req: CpeakRequest, res: CpeakResponse, next: Next) => {
-  // This is only good for bodies that their size is less than the highWaterMark value
-
-  function isJSON(contentType: string = "") {
-    // Remove any params like "; charset=UTF-8"
-    const [type] = contentType.split(";");
-    return (
-      type.trim().toLowerCase() === "application/json" ||
-      /\+json$/i.test(type.trim())
-    );
-  }
-
-  if (!isJSON(req.headers["content-type"] as string)) return next();
-
-  let body = "";
-  req.on("data", (chunk: Buffer) => {
-    body += chunk.toString("utf-8");
-  });
-
-  req.on("end", () => {
-    body = JSON.parse(body);
-    req.body = body;
-    return next();
-  });
+const parseJSON = (options: { limit?: number } = {}) => {
+  // Default limit to 1MB
+  const limit = options.limit || 1024 * 1024;
+
+  return (req: CpeakRequest, res: CpeakResponse, next: Next) => {
+    if (!isJSON(req.headers["content-type"])) return next();
+
+    const chunks: Buffer[] = [];
+    let bytesReceived = 0;
+
+    const onData = (chunk: Buffer) => {
+      bytesReceived += chunk.length;
+
+      // To prevent Denial of Service (DoS) attacks, enforce a maximum body size
+      if (bytesReceived > limit) {
+        // Stop listening to data
+        req.pause();
+
+        // Remove listeners so we don't trigger 'end' or more 'data'
+        req.removeListener("data", onData);
+        req.removeListener("end", onEnd);
+
+        next(
+          frameworkError(
+            "JSON body too large",
+            onData,
+            ErrorCode.PAYLOAD_TOO_LARGE,
+            413 // HTTP 413 Payload Too Large
+          )
+        );
+
+        return;
+      }
+
+      chunks.push(chunk);
+    };
+
+    const onEnd = () => {
+      try {
+        // For better performance, we concat buffers once, then convert to string
+        // Optimization: If only one chunk exists, avoid the memory copy of concat
+        const rawBody =
+          chunks.length === 1
+            ? chunks[0].toString("utf-8")
+            : Buffer.concat(chunks).toString("utf-8");
+
+        // Handle empty body case
+        req.body = rawBody ? JSON.parse(rawBody) : {};
+
+        next();
+      } catch (err) {
+        // Handle Invalid JSON without crashing
+        next(
+          frameworkError(
+            "Invalid JSON format",
+            onEnd,
+            ErrorCode.INVALID_JSON,
+            400 // HTTP 400 Bad Request
+          )
+        );
+      }
+    };
+
+    req.on("data", onData);
+    req.on("end", onEnd);
+  };
 };
 
 export { parseJSON };

package/lib/utils/serveStatic.ts

@@ -17,14 +17,24 @@ const MIME_TYPES: StringMap = {
   ttf: "font/ttf",
   woff: "font/woff",
   woff2: "font/woff2",
+  gif: "image/gif",
+  ico: "image/x-icon",
+  json: "application/json",
+  webmanifest: "application/manifest+json"
 };
 
-const serveStatic = (folderPath: string, newMimeTypes?: StringMap) => {
+const serveStatic = (
+  folderPath: string,
+  newMimeTypes?: StringMap,
+  options?: { prefix?: string }
+) => {
   // For new user defined mime types
   if (newMimeTypes) {
     Object.assign(MIME_TYPES, newMimeTypes);
   }
 
+  const prefix = options?.prefix ?? "";
+
   function processFolder(folderPath: string, parentFolder: string) {
     const staticFiles: string[] = [];
 
@@ -55,9 +65,9 @@ const serveStatic = (folderPath: string, newMimeTypes?: StringMap) => {
     const filesMap: Record<string, { path: string; mime: string }> = {};
     for (const file of filesArray) {
       const fileExtension = path.extname(file).slice(1);
-      filesMap[file] = {
+      filesMap[prefix + file] = {
         path: folderPath + file,
-        mime: MIME_TYPES[fileExtension],
+        mime: MIME_TYPES[fileExtension]
       };
     }
     return filesMap;
@@ -70,8 +80,9 @@ const serveStatic = (folderPath: string, newMimeTypes?: StringMap) => {
     const url = req.url;
     if (typeof url !== "string") return next();
 
-    if (Object.prototype.hasOwnProperty.call(filesMap, url)) {
-      const fileRoute = filesMap[url];
+    const pathname = url.split("?")[0];
+    if (Object.prototype.hasOwnProperty.call(filesMap, pathname)) {
+      const fileRoute = filesMap[pathname];
       return res.sendFile(fileRoute.path, fileRoute.mime);
     }
 

package/lib/utils/swagger.ts

@@ -0,0 +1,31 @@
+import type { CpeakRequest, CpeakResponse, Next } from "../types";
+
+const swagger = (spec: object, prefix = "/api-docs") => {
+  const initializerJs = `window.onload = function() {
+  SwaggerUIBundle({
+    url: "${prefix}/spec.json",
+    dom_id: '#swagger-ui',
+    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+    layout: "StandaloneLayout"
+  });
+};`;
+
+  return (req: CpeakRequest, res: CpeakResponse, next: Next) => {
+    if (req.url === prefix || req.url === `${prefix}/`) {
+      res.writeHead(302, { Location: `${prefix}/index.html` });
+      res.end();
+      return;
+    }
+    if (req.url === `${prefix}/spec.json`) {
+      return res.json(spec);
+    }
+    if (req.url === `${prefix}/swagger-initializer.js`) {
+      res.setHeader("Content-Type", "application/javascript");
+      res.end(initializerJs);
+      return;
+    }
+    next();
+  };
+};
+
+export { swagger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cpeak",
-  "version": "2.4.3",
+  "version": "2.6.0",
   "description": "A minimal and fast Node.js HTTP framework.",
   "type": "module",
   "scripts": {