koa-micro-ts 4.1.1 → 5.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sebastian Hildebrandt
+Copyright (c) 2026 Sebastian Hildebrandt
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -44,12 +44,76 @@ Included middleware/libs:
 - dev/production mode detection - see below in this README.md
 - catch errors - detailed docs [CATCHERRORS.md](docs/CATCHERRORS.md)
 - request stats - detailed docs [REQUESTSTATS.md](docs/REQUESTSTATS.md)
-- integrated API doc - detailed docs [APIDOC.md](docs/APIDOC.md)
+- integrated API doc - auto-generated for all `autoRoute` endpoints - detailed docs [APIDOC.md](docs/APIDOC.md)
 
 Most of these modules can be enabled with just **one line of code**.
 Configuration is super simple and lets you create your micro service within
 minutes.
 
+## New Release 5
+
+Version 5 is a security-hardening release. Based on a full security audit,
+several unsafe defaults were fixed: the built-in CORS middleware no longer
+reflects arbitrary request origins, error responses no longer leak internal
+details in production, the JWT middleware only exposes verified token
+payloads, the generated API doc page is HTML-escaped and request stats can no
+longer grow memory unbounded. It also moves to koa 3 and Node 18+. Most apps
+run unchanged — see the breaking changes and the upgrade path below.
+
+## Version 5 - Breaking Changes
+
+- Dependencies: koa 3
+- minimal node version: node V18
+- CORS: default `credentials: true` → `false`
+- CORS: the default `origin` is now `*` instead of reflecting the request
+  origin. `origin` additionally accepts an array (allowlist) or a function
+  `(ctx) => origin`
+- CORS: `credentials: true` now requires an explicitly configured `origin`
+  (string, allowlist array or function). Without it, CORS headers are omitted
+  instead of reflecting the request origin — see [CORS.md](docs/CORS.md)
+- `catchErrors()`: 5xx responses only contain a generic `Internal Server Error`
+  in production. Full details are still logged and returned in development
+  mode (`app.development`) or when the error sets `expose: true`
+  (Koa convention, e.g. `ctx.throw`) — see [CATCHERRORS.md](docs/CATCHERRORS.md)
+- JWT middleware: `ctx.jwt` now contains only the **verified** token payload
+  (previously the unverified decoded token was set before verification).
+  The payload is also available as `ctx.state.user`
+- SPA fallback (`apiHistoryFallback()`): the Accept header check was fixed —
+  requests accepting `text/html` **or** `*/*` get the fallback (previously
+  both were required, so plain browser requests could miss the fallback)
+- request stats: `pathCounts` is capped at 1000 distinct paths, further paths
+  are aggregated under `(other)`
+- `validators.sanitize()` and `validators.stripAll()` are deprecated — they
+  are not a reliable defense against injection, use parameterized queries and
+  output encoding instead
+
+### Upgrading from v4
+
+1. Make sure you run Node 18 or later, then update the package:
+   `npm install koa-micro-ts@5`.
+2. **CORS with cookies/credentials:** if you call `app.cors({ credentials: true })`
+   without an explicit `origin`, browsers will now be denied. Configure your
+   allowed origins explicitly:
+   ```ts
+   app.cors({
+     origin: ["https://app.example.com"],
+     credentials: true,
+   });
+   ```
+   If you relied on the old reflect-any-origin behavior and really want it
+   (not recommended), pass `origin: (ctx) => ctx.get('Origin')`.
+3. **Error responses:** if clients parse error details from 5xx responses,
+   either throw with `expose: true` / use `ctx.throw(...)`, or handle those
+   errors in your own middleware before `catchErrors()`.
+4. **JWT:** if you read `ctx.jwt` for tokens that fail verification — that is
+   no longer possible; handlers behind `jwt.middleware()` only ever see
+   verified payloads. `ctx.state.user` now works as documented.
+5. **Optional hardening:** protect the stats and API doc endpoints with JWT
+   (`app.stats('/stats', true)`, `app.apiDocAuth = true`) and set body parser
+   limits (`jsonLimit`, `formLimit`, `formidable.maxFileSize`) — see
+   [REQUESTSTATS.md](docs/REQUESTSTATS.md), [APIDOC.md](docs/APIDOC.md),
+   [BODYPARSER.md](docs/BODYPARSER.md).
+
 ## Version 4 - Breaking Change
 
 `app.autoRoute()` is now an async function.
@@ -221,7 +285,7 @@ documentation of the used packages to see their options:
 
 > The [`MIT`][license-url] License (MIT)
 >
-> Copyright © 2025 Sebastian Hildebrandt,
+> Copyright © 2026 Sebastian Hildebrandt,
 > [+innovations](http://www.plus-innovations.com).
 >
 > Permission is hereby granted, free of charge, to any person obtaining a copy

package/dist/apiDoc.d.ts

@@ -1,5 +1,9 @@
 declare const mergeDeep: (target: any, source: any) => any;
 declare const parseFileApiDoc: (fileName: string, secure: boolean) => any;
+declare const parseReducedDocs: (fileName: string) => {
+    [name: string]: string;
+};
+declare const autoDocEntry: (docObj: any, group: string, method: string, path: string, secure: boolean, meta?: any) => void;
 declare const healthDocObj: (healthPath: string, livePath: string) => {
     Health: {
         method: string;
@@ -27,4 +31,4 @@ declare const statsDocObj: (statsPath: string) => {
     }[];
 };
 declare const createHtml: (apiDocObj: any) => string;
-export { createHtml, healthDocObj, mergeDeep, parseFileApiDoc, statsDocObj };
+export { autoDocEntry, createHtml, healthDocObj, mergeDeep, parseFileApiDoc, parseReducedDocs, statsDocObj };