@technomoron/api-server-base 2.0.0-beta.21 → 2.0.0-beta.23

package/package.json

@@ -1,135 +1,130 @@
 {
-	"name": "@technomoron/api-server-base",
-	"version": "2.0.0-beta.21",
-	"description": "Api Server Skeleton / Base Class",
-	"type": "module",
-	"main": "./dist/cjs/index.cjs",
-	"module": "./dist/esm/index.js",
-	"types": "./dist/esm/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/esm/index.d.ts",
-			"import": "./dist/esm/index.js",
-			"require": "./dist/cjs/index.cjs"
-		},
-		"./auth-api/sql-auth-store": {
-			"types": "./dist/esm/auth-api/sql-auth-store.d.ts",
-			"import": "./dist/esm/auth-api/sql-auth-store.js",
-			"require": "./dist/cjs/auth-api/sql-auth-store.js"
-		},
-		"./oauth/sequelize": {
-			"types": "./dist/esm/oauth/sequelize.d.ts",
-			"import": "./dist/esm/oauth/sequelize.js",
-			"require": "./dist/cjs/oauth/sequelize.js"
-		},
-		"./passkey/sequelize": {
-			"types": "./dist/esm/passkey/sequelize.d.ts",
-			"import": "./dist/esm/passkey/sequelize.js",
-			"require": "./dist/cjs/passkey/sequelize.js"
-		},
-		"./token/sequelize": {
-			"types": "./dist/esm/token/sequelize.d.ts",
-			"import": "./dist/esm/token/sequelize.js",
-			"require": "./dist/cjs/token/sequelize.js"
-		},
-		"./user/sequelize": {
-			"types": "./dist/esm/user/sequelize.d.ts",
-			"import": "./dist/esm/user/sequelize.js",
-			"require": "./dist/cjs/user/sequelize.js"
-		}
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/technomoron/api-server-base.git"
-	},
-	"author": "Bjørn Erik Jacobsen",
-	"license": "MIT",
-	"copyright": "Copyright (c) 2025 Bjørn Erik Jacobsen",
-	"bugs": {
-		"url": "https://github.com/technomoron/api-server-base/issues"
-	},
-	"homepage": "https://github.com/technomoron/api-server-base#readme",
-	"scripts": {
-		"scrub": "rm -rf ./node_modules/ pnpm-lock.yaml ./dist/",
-		"build:cjs": "tsc --project tsconfig/tsconfig.cjs.json && node scripts/prepare-cjs.cjs",
-		"build:esm": "tsc --project tsconfig/tsconfig.esm.json",
-		"build": "run-s build:cjs build:esm",
-		"test": "vitest run",
-		"test:unit": "vitest run tests/unit",
-		"test:functional": "vitest run tests/functional",
-		"test:watch": "vitest --watch",
-		"prepublishOnly": "run-s build:cjs build:esm",
-		"lint": "eslint --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
-		"lintfix": "eslint --fix --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
-		"format": "run-s lintfix pretty",
-		"cleanbuild": "rm -rf ./dist/ && run-s format build",
-		"pretty": "prettier --write \"**/*.{js,jsx,cjs,mjs,ts,tsx,mts,vue,json,md}\"",
-		"lintconfig": "node lintconfig.cjs"
-	},
-	"dependencies": {
-		"@simplewebauthn/server": "^13.2.2",
-		"@types/express": "^5.0.6",
-		"bcryptjs": "^3.0.3",
-		"cookie-parser": "^1.4.7",
-		"cors": "^2.8.6",
-		"express": "^5.2.1",
-		"jsonwebtoken": "^9.0.3",
-		"multer": "^2.0.2"
-	},
-	"devDependencies": {
-		"@types/cookie-parser": "^1.4.10",
-		"@types/cors": "^2.8.19",
-		"@types/express-serve-static-core": "^5.1.1",
-		"@types/jsonwebtoken": "^9.0.10",
-		"@types/multer": "^2.0.0",
-		"@types/supertest": "^6.0.3",
-		"@typescript-eslint/eslint-plugin": "^8.54.0",
-		"@typescript-eslint/parser": "^8.54.0",
-		"@vitest/coverage-v8": "4.0.18",
-		"eslint": "^9.39.2",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-import": "^2.32.0",
-		"jsonc-eslint-parser": "^2.4.2",
-		"mysql2": "^3.16.3",
-		"pg": "^8.18.0",
-		"prettier": "^3.8.1",
-		"sequelize": "^6.37.7",
-		"sqlite3": "^5.1.7",
-		"supertest": "^7.2.2",
-		"typescript": "^5.9.3",
-		"vitest": "^4.0.18",
-		"npm-run-all": "^4.1.5"
-	},
-	"peerDependencies": {
-		"mysql2": "^3.16.0",
-		"pg": "^8.16.3",
-		"sequelize": "^6.37.7",
-		"sqlite3": "^5.1.7"
-	},
-	"peerDependenciesMeta": {
-		"mysql2": {
-			"optional": true
-		},
-		"pg": {
-			"optional": true
-		},
-		"sequelize": {
-			"optional": true
-		},
-		"sqlite3": {
-			"optional": true
-		}
-	},
-	"pnpm": {
-		"onlyBuiltDependencies": [
-			"esbuild",
-			"sqlite3"
-		]
-	},
-	"files": [
-		"dist/",
-		"docs/swagger/openapi.json",
-		"package.json"
-	],
-	"packageManager": "pnpm@10.28.2"
-}
+  "name": "@technomoron/api-server-base",
+  "version": "2.0.0-beta.23",
+  "description": "Api Server Skeleton / Base Class",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./auth-api/sql-auth-store": {
+      "types": "./dist/esm/auth-api/sql-auth-store.d.ts",
+      "import": "./dist/esm/auth-api/sql-auth-store.js",
+      "require": "./dist/cjs/auth-api/sql-auth-store.cjs"
+    },
+    "./oauth/sequelize": {
+      "types": "./dist/esm/oauth/sequelize.d.ts",
+      "import": "./dist/esm/oauth/sequelize.js",
+      "require": "./dist/cjs/oauth/sequelize.cjs"
+    },
+    "./passkey/sequelize": {
+      "types": "./dist/esm/passkey/sequelize.d.ts",
+      "import": "./dist/esm/passkey/sequelize.js",
+      "require": "./dist/cjs/passkey/sequelize.cjs"
+    },
+    "./token/sequelize": {
+      "types": "./dist/esm/token/sequelize.d.ts",
+      "import": "./dist/esm/token/sequelize.js",
+      "require": "./dist/cjs/token/sequelize.cjs"
+    },
+    "./user/sequelize": {
+      "types": "./dist/esm/user/sequelize.d.ts",
+      "import": "./dist/esm/user/sequelize.js",
+      "require": "./dist/cjs/user/sequelize.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/technomoron/api-server-base.git",
+    "directory": "packages/server"
+  },
+  "author": "Bjørn Erik Jacobsen",
+  "license": "MIT",
+  "copyright": "Copyright (c) 2025 Bjørn Erik Jacobsen",
+  "bugs": {
+    "url": "https://github.com/technomoron/api-server-base/issues"
+  },
+  "homepage": "https://github.com/technomoron/api-server-base#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@simplewebauthn/server": "^13.2.2",
+    "bcryptjs": "^3.0.3",
+    "jsonwebtoken": "^9.0.3",
+    "fastify": "^5.6.1",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.1.0",
+    "@fastify/multipart": "^9.2.1",
+    "@fastify/static": "^8.3.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/supertest": "^6.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "jsonc-eslint-parser": "^2.4.2",
+    "mysql2": "^3.16.3",
+    "pg": "^8.18.0",
+    "prettier": "^3.8.1",
+    "sequelize": "^6.37.7",
+    "sqlite3": "^5.1.7",
+    "supertest": "^7.2.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "npm-run-all": "^4.1.5"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.16.0",
+    "pg": "^8.16.3",
+    "sequelize": "^6.37.7",
+    "sqlite3": "^5.1.7"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "sequelize": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist/",
+    "docs/swagger/openapi.json",
+    "package.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "scrub": "rm -rf ./node_modules/ pnpm-lock.yaml ./dist/",
+    "build:cjs": "tsc --project tsconfig/tsconfig.cjs.json && node scripts/prepare-cjs.cjs",
+    "build:esm": "tsc --project tsconfig/tsconfig.esm.json",
+    "build": "run-s build:cjs build:esm",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:functional": "vitest run tests/functional",
+    "test:watch": "vitest --watch",
+    "lint": "eslint --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
+    "lintfix": "eslint --fix --no-error-on-unmatched-pattern --ext .js,.cjs,.mjs,.ts,.mts,.tsx,.vue,.json ./",
+    "format": "run-s lintfix pretty",
+    "cleanbuild": "rm -rf ./dist/ && run-s format build",
+    "pretty": "prettier --write \"**/*.{js,jsx,cjs,mjs,ts,tsx,mts,vue,json,md}\"",
+    "lintconfig": "node lintconfig.cjs",
+    "release:check": "bash ./scripts/release-check.sh",
+    "release": "bash ./scripts/release.sh"
+  }
+}

package/README.txt

@@ -1,213 +0,0 @@
-API Server Base
-================
-
-Toolkit for building authenticated Express APIs in TypeScript. ApiServer wraps Express with sensible defaults for JSON parsing, cookie handling, CORS, JWT helpers, and a predictable module system.
-
-- Easy setup of a Node Express based API server with all the basics covered.
-- The server can be extended and methods related to user authentication, API keys and more can be overridden in the derived class.
-- Create API endpoints that are either public, protected or open API calls that may or may not have an authenticated session for dual behaviour.
-- Standardized request handling (POST, GET, file uploads if enabled and more).
-- Authentication system using JWT or simple API bearer keys, fully customizable by overriding class methods (now exposes both the resolved API key and stored token row to handlers).
-- Unified error handling. Just throw new ApiError(...) in any API callback in order ot emit the correct API response.
-- Create structured, standardized API response as JSON data, containing typed return data, response codes and more.
-
-Highlights
-----------
-Strongly typed base classes for servers (ApiServer) and feature modules (ApiModule).
-Consistent request lifecycle with centralized authentication, authorization hook, and tuple based handler responses.
-JWT, cookie, and API key support with overridable extension points.
-No runtime dependencies beyond the Express ecosystem; required packages install automatically.
-Ships ESM and CommonJS builds plus TypeScript declarations for any Node runtime.
-
-Installation
-------------
-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, BaseAuthAdapter } from '@technomoron/api-server-base';
-
-type DemoUser = { id: string; email: string; password: string };
-
-	class DemoStorage extends BaseAuthAdapter<DemoUser, Omit<DemoUser, 'password'>> {
-	private readonly users = new Map<string, DemoUser>([
-		['1', { id: '1', email: 'demo@example.com', password: 'secret' }]
-	]);
-
-	async getUser(uid: unknown) {
-		return this.users.get(String(uid)) ?? null;
-	}
-
-	getUserPasswordHash(user: DemoUser) {
-		return user.password;
-	}
-
-	filterUser(user: DemoUser) {
-		const { password: _password, ...safe } = user;
-		void _password;
-		return safe;
-	}
-}
-
-class AppServer extends ApiServer {}
-
-class UserModule extends ApiModule<AppServer> {
-	constructor() {
-		super({ namespace: '/users' });
-	}
-
-	defineRoutes() {
-		return [
-			{
-				method: 'get',
-				path: '/',
-				auth: { type: 'yes', req: 'any' },
-				handler: async ({ server, tokenData }) => {
-					const storage = server.getAuthStorage();
-					const user = tokenData ? await storage.getUser(tokenData.uid) : null;
-					if (!user) {
-						throw new ApiError({ code: 404, message: 'User not found' });
-					}
-					return [200, storage.filterUser(user)];
-				},
-			},
-		];
-	}
-}
-
-const yourStorageAdapter = new DemoStorage();
-
-	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.
-
-Handlers must return a tuple: [statusCode], [statusCode, data], or [statusCode, data, message]. Throw ApiError for predictable failures.
-
-Configuration Reference
------------------------
-Pass a partial config object to the ApiServer constructor. Defaults cover most values so you can opt in to what you need.
-
-apiPort (number, default 3101) Port the Express app listens on.
-apiHost (string, default 'localhost') Bind address.
-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 '') 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) 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, 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
------------------
-Call `apiReq.getClientInfo()` when you need the entire client fingerprint captured during request hydration. It returns the raw user-agent string plus derived browser/OS/device labels along with the computed `ip` and `ipchain`.
-
-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.
-
-	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
--------------------
-npm run build       Build CommonJS and ESM outputs (dist/cjs, dist/esm).
-npm run build:cjs   Compile using tsconfig/tsconfig.cjs.json.
-npm run build:esm   Compile using tsconfig/tsconfig.esm.json.
-npm run lint        Run ESLint with the flat config (eslint.config.mjs).
-npm run lintfix     Lint and apply autofixes.
-npm run pretty      Run Prettier over common source and documentation files.
-npm run cleanbuild  Remove dist/, format, lint, and rebuild.
-
-Documentation
--------------
-See docs/ folder.
-
-License
--------
-MIT License (see LICENSE). Copyright 2025 Bjorn Erik Jacobsen / Technomoron

package/dist/esm/oauth/base.js

@@ -1,2 +0,0 @@
-export class OAuthStore {
-}

package/dist/esm/passkey/base.js

@@ -1,2 +0,0 @@
-export class PasskeyStore {
-}