@technomoron/api-server-base 1.1.13 → 2.0.0-beta.10

package/README.txt

@@ -108,13 +108,14 @@ cookieDomain (string, default '.somewhere-over-the-rainbow.com') Domain applied
 accessCookie (string, default 'dat') Access token cookie name.
 refreshCookie (string, default 'drt') Refresh token cookie name.
 accessExpiry (number, default 60 * 15) Access token lifetime in seconds.
-refreshExpiry (number, default 30 * 24 * 60 * 60 * 1000) Refresh token lifetime in milliseconds.
+refreshExpiry (number, default 30 * 24 * 60 * 60) Refresh token lifetime in seconds.
 sessionRefreshExpiry (number, default 24 * 60 * 60) Session token lifetime in seconds when clients opt out of "remember me" cookies.
 authApi (boolean, default false) Toggle you can use when mounting auth routes.
 devMode (boolean, default false) Custom hook for development only features.
 debug (boolean, default false) When true the server logs inbound requests via dumpRequest.
 hydrateGetBody (boolean, default true) Copy query parameters into `req.body` for GET requests; set false if you prefer untouched bodies.
 validateTokens (boolean, default false) When true, every JWT-authenticated request must match a stored token row (access token + user id) before reaching your handler. API keys remain stateless either way.
+refreshMaybe (boolean, default false) When true, `auth: maybe` routes will try to refresh a missing/expired access token using the refresh cookie; if refresh fails, the request stays anonymous.
 
 Tip: If you add new configuration fields in downstream projects, extend ApiServerConf and update fillConfig so defaults stay aligned.
 
@@ -122,7 +123,7 @@ Request Lifecycle
 -----------------
 1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
 2. ApiServer wraps the route inside handle_request, setting currReq and logging when debug is enabled.
-3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the `dat` cookie are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
+3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the access cookie (`accessCookie`, default `dat`) are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. When `refreshSecret` is configured and your storage supports refresh lookups (`getToken({ refreshToken })` + `updateToken(...)`), `yes`/`strict` routes will automatically mint a new access token when it is missing or expired (and also recover from "Authorization token is no longer valid" by refreshing). `maybe` routes only do the same when `refreshMaybe: true`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
 4. authorize runs with the requested auth class (any or admin in the base implementation). Override to connect to your role system.
 5. The handler executes and returns its tuple. Responses are normalized to { code, message, data } JSON.
 6. Errors bubble into the wrapper. ApiError instances respect the provided status codes; other exceptions result in a 500 with text derived from guessExceptionText.
@@ -140,6 +141,28 @@ Use your storage adapter's filterUser helper to trim sensitive data before retur
 Provide your own authorize method to enforce role based access control using the ApiAuthClass enum.
 Create feature modules by extending ApiModule. Use the optional checkConfig hook to validate prerequisites before routes mount.
 
+Custom Express Endpoints
+------------------------
+ApiModule routes run inside the tuple wrapper (always responding with a standardized JSON envelope). For endpoints that need raw Express control (streaming, webhooks, tus uploads, etc.), mount your own handlers directly.
+
+- `server.useExpress(...)` mounts middleware/routes and keeps the built-in `/api` 404 handler ordered last, so mounts under `apiBasePath` are not intercepted.
+- Protect endpoints by inserting `server.expressAuth({ type, req })` as middleware. It authenticates using the same JWT/cookie/API-key logic as ApiModule routes and then runs `authorize`.
+- On success, `expressAuth` attaches the computed ApiRequest to both `req.apiReq` and `res.locals.apiReq`.
+- If you want the same JSON error envelope for custom endpoints, mount `server.expressErrorHandler()` after your custom routes.
+
+Example:
+
+	server
+		.useExpress(
+			'/api/custom/optional',
+			server.expressAuth({ type: 'maybe', req: 'any' }),
+			(req, res) => {
+				const apiReq = (req as any).apiReq;
+				res.status(200).json({ uid: apiReq.tokenData?.uid ?? null });
+			}
+		)
+		.useExpress(server.expressErrorHandler());
+
 
 Tooling and Scripts
 -------------------