@technomoron/api-server-base 2.0.0-beta.2 → 2.0.0-beta.20

package/README.txt

@@ -25,13 +25,13 @@ pnpm add @technomoron/api-server-base
 
 All runtime dependencies and `@types/*` packages are bundled with the distribution. The library exports ES modules by default. Consumers that rely on CommonJS can import via the require entry exposed in package.json.
 
-Quick Start
------------
-import { ApiServer, ApiModule, ApiError, BaseAuthStorage } from '@technomoron/api-server-base';
+	Quick Start
+	-----------
+	import { ApiServer, ApiModule, ApiError, BaseAuthAdapter } from '@technomoron/api-server-base';
 
 type DemoUser = { id: string; email: string; password: string };
 
-class DemoStorage extends BaseAuthStorage<DemoUser, Omit<DemoUser, 'password'>> {
+	class DemoStorage extends BaseAuthAdapter<DemoUser, Omit<DemoUser, 'password'>> {
 	private readonly users = new Map<string, DemoUser>([
 		['1', { id: '1', email: 'demo@example.com', password: 'secret' }]
 	]);
@@ -79,14 +79,15 @@ class UserModule extends ApiModule<AppServer> {
 
 const yourStorageAdapter = new DemoStorage();
 
-const server = new AppServer({
-	apiPort: 3101,
-	apiHost: '127.0.0.1',
-	accessSecret: 'replace-me'
-})
-	.authStorage(yourStorageAdapter)
-	.api(new UserModule())
-	.start();
+	const server = new AppServer({
+		apiPort: 3101,
+		apiHost: '127.0.0.1',
+		accessSecret: 'replace-me'
+	})
+		.authStorage(yourStorageAdapter)
+		.api(new UserModule())
+		.finalize()
+		.start();
 
 Need a dedicated auth module as well? Chain `.authModule(...)` in the same spot.
 
@@ -102,30 +103,36 @@ apiBasePath (string, default '/api') Prefix applied to every module namespace.
 origins (string array, default empty array) CORS allowlist; empty allows all origins.
 uploadPath (string, default empty string) Enables multer.any() when provided.
 uploadMax (number, default 30 * 1024 * 1024) Maximum upload size in bytes.
+staticDirs (record, default empty object) Map of mount path => disk path for serving static files as-is (ex: { '/assets': './public' }).
 accessSecret (string, default empty string) Required for JWT signing and verification.
 refreshSecret (string, default empty string) Used for refresh tokens if you implement them.
-cookieDomain (string, default '.somewhere-over-the-rainbow.com') Domain applied to auth cookies.
+cookieDomain (string, default '') Domain applied to auth cookies.
+cookiePath (string, default '/') Path applied to auth cookies.
+cookieSameSite ('lax' | 'strict' | 'none', default 'lax') SameSite attribute applied to auth cookies.
+cookieSecure (boolean | 'auto', default 'auto') Secure attribute applied to auth cookies; 'auto' enables Secure only when the request is HTTPS (or forwarded as HTTPS).
+cookieHttpOnly (boolean, default true) HttpOnly attribute applied to auth cookies.
 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.
 
-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.
-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.
+	Request Lifecycle
+	-----------------
+	1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
+	2. ApiServer wraps the route inside handle_request, creating an ApiRequest and logging when debug is enabled.
+	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.
 
 Client IP Helpers
 -----------------
@@ -133,12 +140,58 @@ Call `apiReq.getClientInfo()` when you need the entire client fingerprint captur
 
 Call `apiReq.getClientIp()` to obtain the most likely client address, skipping loopback entries collected from proxy headers. Use `apiReq.getClientIpChain()` when you need the de-duplicated sequence gathered from the standard Forwarded/X-Forwarded-For/X-Real-IP headers as well as Express' `req.ip`/`req.ips` and the underlying socket. Both helpers reuse the cached payload returned by `apiReq.getClientInfo()`.
 
-Extending the Base Classes
---------------------------
-Implement the AuthStorage contract (getUser, verifyPassword, storeToken, updateToken, etc.) to integrate with your persistence layer, then supply it via authStorage().
-Use your storage adapter's filterUser helper to trim sensitive data before returning responses.
-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.
+	Extending the Base Classes
+	--------------------------
+	Implement the AuthStorage contract (getUser, verifyPassword, storeToken, updateToken, etc.) to integrate with your persistence layer, then supply it via authStorage().
+	Use your storage adapter's filterUser helper to trim sensitive data before returning responses.
+	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.
+
+	OAuth Client Secrets
+	--------------------
+	If your OAuth client records use a client secret, make `getClient(clientId)` return a client with a truthy `clientSecret` (do not return the stored hash/secret itself) and implement `verifyClientSecret(client, clientSecret)` on your storage adapter. If `clientSecret` is truthy but `verifyClientSecret` is not overridden, the `/auth/v1/oauth2/token` endpoint returns 501.
+
+	Sequelize Table Prefixes
+	------------------------
+	Sequelize-backed stores accept `tablePrefix` to prepend to the built-in table names (`users`, `jwttokens`, `passkey_credentials`, `passkey_challenges`, `oauth_clients`, `oauth_codes`).
+
+SqlAuthStore supports both a global prefix (`tablePrefix`) and per-module overrides (`tablePrefixes.user|token|passkey|oauth`). When present, `tokenStoreOptions.tablePrefix` and `oauthStoreOptions.tablePrefix` take precedence.
+
+Example:
+
+	const store = new SqlAuthStore({
+		sequelize,
+		tablePrefix: 'myapp_'
+	});
+	// Creates tables like myapp_users, myapp_jwttokens, myapp_oauth_clients, ...
+
+If you need a different base name (for example `myapp_tokens` instead of `myapp_jwttokens`), pass a custom model or model factory to the store and set the `tableName` yourself.
+
+	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());
+
+	Finalize And Start
+	------------------
+	Call `server.finalize()` after you have mounted all ApiModules and custom Express endpoints. After finalize (or after `start()`), calling `api()` / `useExpress()` will throw.
 
 
 Tooling and Scripts

package/dist/cjs/api-module.cjs

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiModule = void 0;
 class ApiModule {
+    get server() {
+        if (this._server === undefined) {
+            throw new Error('ApiModule.server is not set. Mount the module with ApiServer.api(...) before using it.');
+        }
+        return this._server;
+    }
+    set server(value) {
+        this._server = value;
+    }
     constructor(opts = {}) {
         this.mountpath = '';
         this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';

package/dist/cjs/api-module.d.ts

@@ -1,12 +1,13 @@
 import type { ApiRequest } from './api-server-base.js';
-export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
+export type ApiHandlerResult<Data = unknown> = [number] | [number, Data] | [number, Data, string];
+export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHandlerResult<Data>>;
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
     uid: unknown;
 }
 export type ApiRoute = {
-    method: 'get' | 'post' | 'put' | 'delete';
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
     path: string;
     handler: ApiHandler;
     auth: {
@@ -14,8 +15,10 @@ export type ApiRoute = {
         req: ApiAuthClass;
     };
 };
-export declare class ApiModule<T> {
-    server: T;
+export declare class ApiModule<T = unknown> {
+    private _server?;
+    get server(): T;
+    set server(value: T);
     namespace: string;
     mountpath: string;
     static defaultNamespace: string;