@jongleberry/api-server 1.0.3 → 1.1.0

package/dist/application.d.mts

@@ -16,6 +16,7 @@ export declare class Application extends EventEmitter {
     private logger;
     private bodyLimit;
     private trustProxy;
+    private strictJsonContentType;
     constructor(options?: ApplicationOptions);
     route(path: string): RouteBuilder;
     errorHandler(fn: ErrorHandler): void;

package/dist/application.mjs

@@ -4,7 +4,7 @@ import { createRouteBuilder } from "./router.mjs";
 import Router from "find-my-way";
 import { ServerTiming } from "./server-timing.mjs";
 import { Logger } from "./logger.mjs";
-import { getFallbackBody, getFallbackStatus, sendFallback } from "./fallback-response.mjs";
+import { ensureFallbackHeaders, getFallbackBody, getFallbackStatus, safeString, sendFallback, SECURITY_HEADERS, } from "./fallback-response.mjs";
 export class Application extends EventEmitter {
     router = Router();
     errorHandlerFn = null;
@@ -15,11 +15,13 @@ export class Application extends EventEmitter {
     logger;
     bodyLimit;
     trustProxy;
+    strictJsonContentType;
     constructor(options) {
         super();
         this.logger = new Logger(options?.logger);
         this.bodyLimit = options?.bodyLimit ?? "1mb";
         this.trustProxy = options?.trustProxy ?? false;
+        this.strictJsonContentType = options?.strictJsonContentType ?? false;
     }
     route(path) {
         return createRouteBuilder(this.router, path);
@@ -47,7 +49,7 @@ export class Application extends EventEmitter {
             // Safety net: if runRequest rejects before its own try-catch (e.g. during
             // context/timing setup), ensure the client always gets a response instead
             // of a socket hang-up from an unhandled promise rejection.
-            const error = err instanceof Error ? err : new Error(String(err));
+            const error = err instanceof Error ? err : new Error(safeString(err));
             try {
                 if (this.listenerCount("error") > 0) {
                     this.emit("error", error);
@@ -57,6 +59,7 @@ export class Application extends EventEmitter {
                 // Swallow listener throws so the 500 response still goes out.
             }
             if (!res.headersSent) {
+                ensureFallbackHeaders(res);
                 res.writeHead(500);
                 res.end("Internal Server Error");
             }
@@ -78,17 +81,15 @@ export class Application extends EventEmitter {
             }
         });
         const { onWriteHead, onFinish } = this.logger.onRequestStart(req);
-        const ctx = new ContextClass(req, res, {}, timing, this.asyncLocalStorage, abortController, this.bodyLimit, this.trustProxy, onWriteHead);
+        const ctx = new ContextClass(req, res, {}, timing, this.asyncLocalStorage, abortController, this.bodyLimit, this.trustProxy, onWriteHead, this.strictJsonContentType);
         // Security headers
-        res.setHeader("X-XSS-Protection", "0");
-        res.setHeader("X-Frame-Options", "SAMEORIGIN");
-        res.setHeader("X-Content-Type-Options", "nosniff");
+        for (const [name, value] of Object.entries(SECURITY_HEADERS)) {
+            res.setHeader(name, value);
+        }
         try {
             const method = req.method ?? "GET";
             const url = req.url ?? "/";
-            const rawPath = url.startsWith("http://") || url.startsWith("https://")
-                ? new URL(url).pathname
-                : url.split("?")[0];
+            const rawPath = getRawPath(url);
             const routePath = rawPath.replace(/^\/+/, "/") || "/";
             const found = this.router.find(method, routePath);
             if (found) {
@@ -100,6 +101,7 @@ export class Application extends EventEmitter {
                     await this.notFoundHandlerFn(ctx);
                 }
                 else {
+                    ensureFallbackHeaders(res);
                     res.writeHead(404);
                     res.end("Not Found");
                 }
@@ -107,7 +109,7 @@ export class Application extends EventEmitter {
             onFinish(res.statusCode);
         }
         catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+            const error = err instanceof Error ? err : new Error(safeString(err));
             if (this.listenerCount("error") > 0) {
                 this.emit("error", error);
             }
@@ -129,6 +131,7 @@ export class Application extends EventEmitter {
             }
             else if (!res.headersSent) {
                 const status = getFallbackStatus(error);
+                ensureFallbackHeaders(res);
                 res.writeHead(status);
                 res.end(getFallbackBody(error, status));
             }
@@ -136,4 +139,16 @@ export class Application extends EventEmitter {
         }
     }
 }
+function getRawPath(url) {
+    const lower = url.slice(0, 8).toLowerCase();
+    if (lower.startsWith("http://") || lower.startsWith("https://")) {
+        try {
+            return new URL(url).pathname;
+        }
+        catch {
+            throw Object.assign(new Error("Invalid URL"), { status: 400 });
+        }
+    }
+    return url.split("?")[0];
+}
 export const createApp = (options) => new Application(options);

package/dist/context.d.mts

@@ -18,7 +18,7 @@ export declare class Context {
     private queryCache;
     private asyncLocalStorage;
     private trustProxy;
-    constructor(req: IncomingMessage, res: ServerResponse, params: Record<string, string | undefined>, timing: ServerTiming, als: AsyncLocalStorage<unknown> | null, abortController: AbortController, bodyLimit: string | number | false, trustProxy: boolean, onWriteHead?: () => void);
+    constructor(req: IncomingMessage, res: ServerResponse, params: Record<string, string | undefined>, timing: ServerTiming, als: AsyncLocalStorage<unknown> | null, abortController: AbortController, bodyLimit: string | number | false, trustProxy: boolean, onWriteHead?: () => void, strictJsonContentType?: boolean);
     get query(): Record<string, string | string[]>;
     get store(): unknown;
     get ip(): string | undefined;

package/dist/context.mjs

@@ -26,11 +26,11 @@ export class Context {
     queryCache = null;
     asyncLocalStorage;
     trustProxy;
-    constructor(req, res, params, timing, als, abortController, bodyLimit, trustProxy, onWriteHead) {
+    constructor(req, res, params, timing, als, abortController, bodyLimit, trustProxy, onWriteHead, strictJsonContentType) {
         this.req = req;
         this.res = res;
         this.params = params;
-        this.request = new Request(req, res, bodyLimit);
+        this.request = new Request(req, res, bodyLimit, strictJsonContentType ?? false);
         this.response = new Response(req, res, timing, onWriteHead);
         this.cookies = new Cookies(req, res);
         this.abortController = abortController;

package/dist/fallback-response.d.mts

@@ -1,4 +1,16 @@
-import type { ServerResponse } from "node:http";
+import { type ServerResponse } from "node:http";
+export declare const SECURITY_HEADERS: {
+    readonly "X-XSS-Protection": "0";
+    readonly "X-Frame-Options": "SAMEORIGIN";
+    readonly "X-Content-Type-Options": "nosniff";
+    readonly "Strict-Transport-Security": "max-age=15552000; includeSubDomains";
+    readonly "Referrer-Policy": "no-referrer";
+    readonly "X-DNS-Prefetch-Control": "off";
+    readonly "X-Download-Options": "noopen";
+    readonly "X-Permitted-Cross-Domain-Policies": "none";
+};
+export declare function ensureFallbackHeaders(res: ServerResponse): void;
 export declare function sendFallback(res: ServerResponse): void;
 export declare function getFallbackStatus(error: unknown): number;
+export declare function safeString(err: unknown): string;
 export declare function getFallbackBody(error: unknown, status: number): string;

package/dist/fallback-response.mjs

@@ -1,8 +1,37 @@
+import { STATUS_CODES } from "node:http";
 const FALLBACK_BODY = "Not Found";
 const ERROR_STATUS = 500;
 const ERROR_BODY = "Internal Server Error";
+const TEXT_PLAIN_CONTENT_TYPE = "text/plain; charset=utf-8";
+export const SECURITY_HEADERS = {
+    "X-XSS-Protection": "0",
+    "X-Frame-Options": "SAMEORIGIN",
+    "X-Content-Type-Options": "nosniff",
+    "Strict-Transport-Security": "max-age=15552000; includeSubDomains",
+    "Referrer-Policy": "no-referrer",
+    "X-DNS-Prefetch-Control": "off",
+    "X-Download-Options": "noopen",
+    "X-Permitted-Cross-Domain-Policies": "none",
+};
+const FALLBACK_HEADERS = {
+    "Content-Type": TEXT_PLAIN_CONTENT_TYPE,
+    ...SECURITY_HEADERS,
+};
+export function ensureFallbackHeaders(res) {
+    for (const [name, value] of Object.entries(FALLBACK_HEADERS)) {
+        try {
+            if (typeof res.hasHeader !== "function" || !res.hasHeader(name)) {
+                res.setHeader(name, value);
+            }
+        }
+        catch {
+            // Header mutation can fail on destroyed sockets or non-standard responses.
+        }
+    }
+}
 export function sendFallback(res) {
     try {
+        ensureFallbackHeaders(res);
         res.writeHead(ERROR_STATUS);
         res.end(ERROR_BODY);
     }
@@ -17,9 +46,30 @@ export function getFallbackStatus(error) {
     }
     return ERROR_STATUS;
 }
+function escapeHtml(unsafe) {
+    return unsafe
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#039;");
+}
+export function safeString(err) {
+    try {
+        return String(err);
+    }
+    catch {
+        return "[Object null prototype]";
+    }
+}
 export function getFallbackBody(error, status) {
     if (status >= 500)
         return ERROR_BODY;
-    const message = error?.message;
-    return typeof message === "string" && message ? message : FALLBACK_BODY;
+    const err = error;
+    const message = err?.message;
+    if (err?.expose === false) {
+        return STATUS_CODES[status] || FALLBACK_BODY;
+    }
+    const msg = typeof message === "string" && message ? message : STATUS_CODES[status] || FALLBACK_BODY;
+    return escapeHtml(msg);
 }

package/dist/logger.mjs

@@ -27,8 +27,8 @@ export class Logger {
             return this.createErrorLevelLogger(req);
         }
         const slot = this.assignSlot();
-        const method = req.method ?? "GET";
-        const url = req.url ?? "/";
+        const method = sanitize(req.method ?? "GET");
+        const url = sanitize(req.url ?? "/");
         const startTime = process.hrtime.bigint();
         this.print("──‣", "┈┈┈┈┈", method, url, "┬", slot);
         return {
@@ -44,8 +44,8 @@ export class Logger {
         };
     }
     createErrorLevelLogger(req) {
-        const method = req.method ?? "GET";
-        const url = req.url ?? "/";
+        const method = sanitize(req.method ?? "GET");
+        const url = sanitize(req.url ?? "/");
         const startTime = process.hrtime.bigint();
         return {
             onWriteHead: noop,
@@ -109,3 +109,9 @@ export class Logger {
     }
 }
 function noop() { }
+function sanitize(str) {
+    // eslint-disable-next-line no-control-regex
+    return str
+        .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")
+        .replace(/[\x00-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, "");
+}

package/dist/request.d.mts

@@ -4,7 +4,8 @@ export declare class Request {
     private res;
     private bodyPromise;
     private defaultLimit;
-    constructor(req: IncomingMessage, res: ServerResponse, defaultLimit?: string | number | false);
+    private strictJsonContentType;
+    constructor(req: IncomingMessage, res: ServerResponse, defaultLimit?: string | number | false, strictJsonContentType?: boolean);
     is(type: string | string[]): string | false | null;
     buffer(limit?: string | number | false): Promise<Buffer>;
     json<T = unknown>(limit?: string | number | false): Promise<T>;

package/dist/request.mjs

@@ -8,10 +8,12 @@ export class Request {
     res;
     bodyPromise = null;
     defaultLimit;
-    constructor(req, res, defaultLimit = "1mb") {
+    strictJsonContentType;
+    constructor(req, res, defaultLimit = "1mb", strictJsonContentType = false) {
         this.req = req;
         this.res = res;
         this.defaultLimit = defaultLimit;
+        this.strictJsonContentType = strictJsonContentType;
     }
     is(type) {
         return typeIs(this.req, Array.isArray(type) ? type : [type]);
@@ -27,6 +29,23 @@ export class Request {
         return this.bodyPromise;
     }
     async json(limit) {
+        if (this.strictJsonContentType) {
+            // type-is semantics:
+            //   null  → no body (no Content-Length / Transfer-Encoding header);
+            //           skip the content-type check — buffer() will return an empty
+            //           buffer that JSON.parse rejects with 400 as usual.
+            //   false → a body is indicated but Content-Type is not a JSON type.
+            //           We 415 only when the body actually has content (CL > 0 or
+            //           Transfer-Encoding is set without CL). A Content-Length: 0
+            //           body has nothing to read, so let it fall through to 400.
+            //   truthy → recognised JSON type; proceed normally.
+            const mediaType = this.is(["json", "application/*+json"]);
+            const cl = this.req.headers["content-length"];
+            const emptyBody = cl !== undefined && Number(cl) === 0;
+            if (mediaType === false && !emptyBody) {
+                throw Object.assign(new Error("Unsupported Media Type"), { status: 415 });
+            }
+        }
         const buf = await this.buffer(limit);
         try {
             return JSON.parse(buf.toString("utf8"));

package/dist/types.d.mts

@@ -12,4 +12,13 @@ export interface ApplicationOptions {
     bodyLimit?: string | number | false;
     logger?: LoggerOptions;
     trustProxy?: boolean;
+    /**
+     * When true, ctx.request.json() rejects requests whose Content-Type is not
+     * application/json (or a compatible JSON subtype such as application/merge-patch+json)
+     * with a 415 Unsupported Media Type error. Requests with no body are unaffected.
+     *
+     * Defaults to false (lenient: any Content-Type is accepted, preserving
+     * backward-compatible behavior).
+     */
+    strictJsonContentType?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jongleberry/api-server",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "A Node.js HTTP server library",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -44,7 +44,7 @@
     "@types/type-is": "^1.6.7",
     "@vitest/coverage-v8": "^4.1.6",
     "husky": "^9.1.7",
-    "oxfmt": "^0.50.0",
+    "oxfmt": "^0.51.0",
     "oxlint": "^1.65.0",
     "supertest": "^7.2.2",
     "typescript": "^6.0.3",